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1. Introduction 



Purpose of manual 

This manual provides a description of the Resident Operating System 
for the ATARI Personal Computer System, for use by persons concerned 
with the internal behavior of the systems. This manual discusses: 

o The functions provided by the system and how to use them 
o The organization of the various subsystems 

o The characteristics of the ATARI peripheral devices which may 
be attached 

o Standard techniques for going beyond the basic OS 

capabilities 
o The general nature of the hardware involved 

This manual assumes that the reader is already familiar with 
programming concepts and jargon, assembly language programming in 
general and with the Synertek 6502 in particular, and has some degree 
of familiarity with digital hardware. The primary intent is to provide 
an experienced programmer with sufficient information so that he or 
she can effectively utilize the resources provided by the OS without 
having to resort to OS listings or trial and error techniques. A 
secondary goal is to provide supporting information for those 
individuals who do have to work with the OS listings. 

This manual does not attempt to describe the hardware being used to 
provide the OS capabilites in any comprehensive fashion. Therefore, 
the person wanting to go beyond the capabilities described here are 
advised to examine the ATARI Personal Computer System HARDWARE MANUAL. 
This applies mostly to persons involved in the design of game 
cartridges, where display requirements, system timing and/or memory 
requirements preclude usage of the OS for one or more functions. 



General description of the ATARI Personal Computer System 

The ATARI 40C? M and ATARI SOCPfcer sona 1 Computer Systems are virtually 
identica) from the standpoint of the operating system. In fact, the OS 
is identical in both models. The primary differences between the ATARI 
400 and ATARI 800 Personal Computer Systems are: 

o Physical packaging 

o The ATARI 400 console has one cartridge slot, the ATARI 800 

console has two slots 
o The ATARI 400 Personal Computer System can be expanded from 8k 

to 16K RAM maximum, the ATARI 800 Personal Computer System can 

be expanded to 48K RAM maximum 

The hardware contains circuitry to: produce both character and point 
graphics for B&W or color television, produce four independent audio 
channels (frequency controlled) which use the television sound system, 
provide one bi-level audio output in the base unit, interface to up to 
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4 joysticks, 8 paddle controllers/4 driving controllers, light pen, 
interface to a serial I/O bus for expansion, and has a built in 
keyboard. A simplified block diagram of the hardware is shown on th 
next page. 

See the ATARI Personal Computer System HARDWARE MANUAL (part number 
C016555 > for supporting documentation. 
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ATARI Personal Computer System Block Diagram 
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Notations used in this manual 

Several special notations are used throughout this manual in order to 
concisely present certain types of information such as hexadecimal 
numbers, memory addresses and data syntax. These notations are 
explained in the paragraphs that follow. 



MEMORY ADDRESSES 

All references to computer memory (and mapped I/O) locations will be 

in hexadecimal notation; sometimes the addresses will be contained in 

square brackets, such as 'CD20F3', and sometimes not, such as 'D20F'. 



HEXADECIMAL NUMBERS 

All two digit numbers preceded by a dollar sign ('$') are to be read 
as hexadecimal numbers. Where not so prefixed, or specified otherwise 
by supporting text, a number that is not a memory address is expressed 
in decimal. 



KILOBYTES OF MEMORY 

Memory sizes are frequently expressed in units of kilobytes, such as 
32K, where a kilobyte is 1024 bytes of memory. 



PASCAL AS AN ALGORITHM SPECIFICATION LANGUAGE 

In the few places where an algorithm is specified in detail/ the 
Pascal language (procedure block only) is used as the specification 
language. Pascal syntax is similar to that of any number of other 
block structured languages, and the user should have no difficulty 
following the code presented. 



MEMORY LAYOUTS 

Whenever pictures of bytes or tables are presented, figures similar to 
the one shown below are used: 
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— this is a single byte. 



+ this is a word (2 bytes) 



this is a block of memory 
of unspecified length. 



Where bit-7 is the most significant bit (msb) of the byte, and bit-0 
is the least significant bit <lsb). 

In table figures, memory addresses always increase toward the bottom 
of the figure. 



BACKUS-NAUR FORM < BNF ) 

A modified version of BNF is used to express some syntactic forms, 
where the following me ta- 1 ing u i s t i c symbols are used: 

is the substitution (assignment) operator. 

< > bracket a me tasyntac t i c variable. 

! separates alternative substitutions. 

C 3 bracket an optional construct. 

anything else is a syntactic literal constant, which stands for 
itself. 

For example: 

Cdevice specification!:^ :: = <device name>C<d evi c e number>D: 
•Cdevice name> :: = CID1E!K1P1R!S 
<device number> ::= 1121314 

The above statements specify that something called a "device 
specification" consists of a mandatory "device name* 1 followed by an 
optional "device number 11 followed by the character ': The "device 
name"; in turn, must be one and only one of the characters shown as 
alternatives; while the "device number" (if it is present) must be a 
digit 1 through 4. 



OS EQUATE FILE NAMES 

Operating system ROM and RAM vector names, RAM database variable names 
and hardware register names are all referred to herein by the names 
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assigned in the OS program equate list; in most cases, when one of 
these names is used, the memory address is provided also, such as 
'BOOTAD C0242]'. 
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2. Operating System functional organization 

This section describes the various subsystems of the resident 
OS in general terms. 



I/O subsystem 

The I/O subsystem provides a high-level interface between the programs 
and the hardware. Most functions are device independent/ such as the 
reading and writing of character data; yet provisions have been made 
for device dependent functions as well. All peripheral devices capable 
of dealing with character data have individual symbolic names (such as 
K/D/P/ etc. ) and may be accessed using a Central I/O (CIO) routine. 

Controllers such as joysticks/ paddle controllers and the light pern 
which do not deal with character data; are accessed via a RAM data 
base which is periodically updated to show the states of these 
devices. 



Interrupt processing 

All hardware interrupts are handled in a common and consistent manner 
by the Interrupt subsystem. By default/ all interrupts are fielded by 
the OS/ but at the discretion of the user/ individual interrupts (or 
groups of interrupts) may be fielded by the application program. 

Initial i zat ion 

There are two levels of initialization provided by the system: power 
up and CRESETD. Power up initialization is performed each time the 
system power is turned on/ and CRESET3 initialization is performed 
each time the CRESET3 key is pressed. 



Power up 

Whenever system power is turned on/ the OS examines and notes the 
configuration of the unit; the following items are among those things 
performed at power up: 

o Determine the highest RAM address. 

o Clear all of RAM to zeroes. 

o Establish all RAM interrupt vectors. 

o Format the Device Table. 

o Initialize the cartr idge ( s ) . 

o Setup the screen for 24 x 40 text mode. 

o Boot the cassette if directed. 

o Check cartridge slot(s) for disk boot instructions, 

o Boot the disk if directed to do so and a disk is attached, 

o Transfer control to the cartridge/ disk booted program/ 
cassette booted program/ or blackboard program. 
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CRESET3 

Whenever the CRESETD key is pressed, the OS performs some, but not 
all/ of the functions performed at power up; the following items are 
among those things performed as a result of pressing the CRESETD key 

o Clear the OS portion of RAM. 

o Re-establish all RAM interrupt vectors. 

o Format the Device Table. 

o Initialize the cartr idge ( s ) . 

o Setup the screen for 24 x 40 text mode. 

o Transfer control to the cartridge, disk booted program, 
cassette booted program, or blackboard program. 

Floating point arithmetic package 

Contained within the OS ROM is a floating point (FP) package which i 
not used by the other parts of the OS itself, but is available to 
non-resident programs such as BASIC, Calculator, Pascal, etc. The 
floating point numbers are stored as 10 BCD digits of mantissa plus 
1 byte exponent. The following routines are among those found in the 
package: 

o ASCII to FP and FP to ASCII conversion. 

o Integer to FP and FP to integer conversion. 

o FP add, subtract, multiply and divide. 

o FP log, exp and polynomial evaluation. 

o FP number clear, load, store and move. 
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3. Configurations 

The ATARI 400 and ATARI 800 Personal Computer Systems support a wide 
variety of configurations/ each with a unique operating environment: 
cartridge(s) may or may not be inserted, memory may be optionally 
added to the ATARI 800 computer console in 8K or 16K increments, and 
many different peripheral devices may be attached to the serial I/O 
bus. The OS accounts for all of these variables without requiring a 
change in the resident OS itself As explained in Section 2, the 
machine configuration is checked when power is first turned on and 
then is not checked again. A general discussion of some of the valid 
configurations fol lows. 

Program environments 

The OS allows one of four program types to be in control at any point 
in time: the OS blackboard (ATARI Memo Pad) program, a cartridge 
resident program, a disk booted program or a cassette booted program. 
Which one of these is in control is based upon information in the 
cartr idge ( s ) , whether or not a disk is attached and operator keyboard 
inputs; the exact algorithms are discussed in detail in section 7. 

Blackboard mode 

When in blackboard mode, the screen is established as a 24 x 40 
text screen. Anything entered from the keyboard goes to the 
screen without being examined; although all of the screen 
editing functions are supported. Blackboard mode is the lowest 
priority environment; one only goes there if there is no other 
reasonable environment for the OS to enter or if the operator 
requests a higher priority environment to enter the blackboard 
mode (for example, BYE in BASIC). If it was entered from a higher 
priority environment, the blackboard mode may be exited by pressing 
the CRESETH key. 



Cartridge 

When a cartridge is inserted, it normally provides the main control 
after initialization is complete; for example: BASIC, 
Super BreakoutJB>, BASKETBALL, COMPUTER CHESS, etc. all interface 
directly with the user in some way. Although it is possible for a 
cartridge to provide a supporting function for some other program 
environment, this has not yet been done. In some cartridges, 
particularly keyboard oriented ones, it possible to change 
environments by entering special commands such as "BYE" to go to 
blackboard mode or "DOS" to enter the Disk Utility. In many other 
cartridges, particulary games, it is not possible to change 
environments. Note that because of a hardware interlock it is 
impossible to remove or insert a cartridge with the power on; this 
means (among other things; that every cartridge change will completely 
reinitialize the entire system. 
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Disk boot 

When the system powers up with a disk attached with disk bootable 
software, the disk may or may not be booted, depending upon conditions 
explained in section 7. The rest of this paragraph assumes that a disk 
boot did occur. 

The disk booted software may take control as the Disk Utility does 
under certain conditions, or may provide a supporting function as the 
File Management System does; this environment is so flexible that it 
is difficult to generalize on its capabilities and restrictions. The 
only machine requirement (other than the disk drive) is that 
sufficient RAM be installed to support the program being booted. 

Cassette boot 

Everything that was said about the disk boot environment is also true 
about the cassette boot environment, although the cassette is limited 
as an I/O device due to its slowness, sequential access and single 
file at a time nature. Those limitations probably limit cassette 
booted software to "cartridge type" programs, 100 percent RAM resident 
and not involving random access nor much I/O involving permanent 
storage. Note that the cassette boot facility has no relation to the 
use of cassettes to store high level language programs (e.g. programs 
written in BASIC) nor to the use of cassettes to store data. 

RAM expansion 

Although RAM may be expanded non-c on t i g uous 1 y by the user in the ATARI 
800 Personal Computer System, the OS will only recognize RAM that is 
contiguous starting from location 0. Directions for installing the RAM 
modules are provided with the purchased modules. RAM may be added 
until it totals 48K; after 32K, additional RAM overlays first the 
right cartridge addresses ( 32K to 40K ) and then the left cartridge 
addresses <40K to 48K). Note that in cases of conflict, the inserted 
cartridge has higher priority and disables the conflicting RAM in 8K 
increments. See section 4 for a detailed discussion of system memory. 

As a result of power up the OS will generate two pointers that define 
the lowest available RAM location and the highest available RAM 
location. The OS and d i s k /cassette booted software will determine the 
location of the lowest available RAM, while the number of RAM modules 
and the current screen mode will determine the highest available RAM. 

Peripheral devices 

Peripheral devices of several types may be added to the system using 
standard cables to either the serial bus or the connectors at the 
front of the computer console. The most common types deal with either 
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transmission of bytes of data (usually serial bus) or transmission of 
sense information (usually game controllers). 

Game controllers 

The standard game controllers (pots/ joysticks/ driving controllers/ 
light pen, etc.) are sensed periodically (50 or 60 times per second) 
by the OS and the values read are stored in RAM. These controllers may 
be plugged in* pulled out/ and rearranged at will by the user without 
affecting system operation; the system will always try to read all of 
these controllers. Other controllers/ such as the keyboard controller/ 
are not read by the OS and special instructions as described in 
section 11 are required to read them. 



Cassette 

The cassette is a special peripheral in that it uses the serial bus to 
send and receive data/ but does not conform to the protocol of the 
other peripherals that use the serial bus. The cassette must also be 
the last device on the serial bus because it does not have a serial 
bus extender connector as the other peripherals do. The lack of a bus 
extender assures that there is never more than one cassette drive 
connected to any system. The system cannot sense the absence or 
presence of the cassette drive/ so it may be connected and 
disconnected at will. 



Serial bus devices 

By serial bus devices we mean those that conform to the serial I/O bus 
protocol as defined in section 9; this does not include the cassette 
drive. Each serial bus device has two identical connectors: one a 
serial bus input/ the other a serial bus extender. Either connector 
may be used for either purpose, and peripherals may be M daisy chained" 
simply be cabling them together in a sequential fashion. There are 
usually no restrictions on the cabling order/ as each device has a 
unique identifier; where there are restrictions/ they will be 
mentioned in section 5. 
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4. System memory utilization 

Memory in the system is decoded in the full 64K range of the 6502 

microcomputer and there are no provisions for additional mapping to 

extend memory. Memory is divided into four basic regions (with some 
overlap possible): RAM/ cartridge area, I/O region and the resident OS 

ROM. The regions and their address boundaries are listed below (all 
addresses are in hexadecimal): 

000Q-1FFF = RAM (minimum required for operation) 
2000-7FFF = RAM ex pansion area 

8000-9FFF = Cartridge B, Cartridge B (half of 16K size) or RAM 
AOOO-BFFF = Cartridge A or RAM 
COOO-CFFF = unused 

D000-D7FF = Hardware I/O decodes 
D800-DFFF ■ Floating point package (OS) 
EOOO=FFFF = Resident Operating System ROM 

This section will break these regions into even smaller functional 
divisions and provide detailed explanations of their usage. 



RAM region 

The RAM region is shared between the OS and the program in control 
and can be further subdivided into the following sub— regions for 
discussion purposes: 

Page 0 = 6502 page zero address mode region. 

Page 1 = 6502 stack region. 

Pages 2-4 = OS database & user workspace. 

Pages 5-6 = User program workspace. 

Pages 7-XX ■ Bootable software area/free RAM*. 

Pages XX-top of RAM = screen display list and data*. 

* Note that XX is a function of the screen graphics mode and the 
amount of RAM installed. 

The paragraphs that follow indicate the OS usage and recommended user 
program usage of these RAM sub-regions. 



Page 0 

Because of the architecture of the 6502 microcomputer instruction set 
and addressing modes/ page O has special significance; references to 
addresses in that page (0000 to OOFF ) are faster, require fewer 
instruction bytes and provide the only mechanism for hardware indirect 
addressing. Therefore page 0 is a resource that has to be utilized 
sparingly so that all possible users may have portion of it. The OS 
permanently takes the lower half of page 0 (0000 to 007F) and this 
portion may never be used by any outer environment unless the OS is 
completely disabled and all interrupts to the OS are eliminated. 
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The upper half of page O (0080 to OOFF) is available to outer 
envirnments with the following restriction: the floating point 
package; if used/ requires 00D4 through OOFF. 



Page 1 



Heavily u$*xf 



Page 1 is the 6502 hardware stack region; JSR instructions* PHA 
instructions and interrupts all cause data bytes to be written to page 
1 and conversely RTS, PLA/ and RTI instructions all cause data bytes 
to be read from page 1. The 256 byte stack is adequate for normal 
subroutine calls plus interrupt process nesting/ so no restrictions 
have been made on page 1 usage. It is obvious that a stack of this 
size is totally inadequate for deeply recursive processes or for 
nested processes with large local environments to be saved. So, for 
sophisticated applications/ software maintained stacks must be 
imp 1 emen ted . 

The 6502 stack pointer is initialized at power up or CRESET3 to point 



to location 01FF/ the stack then pushes downward toward 0100. 
stack will wrap around from 0100 to 01FF if a stack overflow 
condition occurs/ due to the nature of the 6502's 8-bit stack 
register. 



The 

pointer 



OS database 



Locations 0200 through 047F are allocated by the OS for working 
variables/ tables and data buffers. Portions of this region may be 
used only after it is determined that nonconflict with the OS is 
guaranteed. For example/ the printer and cassette buffers could be 
used if I/O operations to these devices are impossible within the 
controlling environment. The amount of work involved in determining 
nonconflict seems to be completely out of line with the benefits to 
gained (except for a few trivial cases) and it is recommended that 
pages 2 through not be used except by the OS. 



be 



User workspace 

Locations 0480 through 06FF are dedicated 
except when the floating point package is 

057E through 05FF. ^ 

7 



for outer environment use 
used/ in which case it uses 



region 



Page 7 is the start of the "boot region". When software is booted from 
either the disk or the cassette/ it may start at the lowest free 
memory address (which is 0700) and proceed upward (although it may 
also start at any address above 0700 and below the screen display 
list). The top of this region defines the start of the "free memory" 
region When the boot process is complete/ a pointer in the data base 
contains the address of the next available location above the software 
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just booted. When no software has been booted/ this pointer contains 
the value 0700. 



Screen display list and data 

When the OS is handling the screen display, the display list^which 
defines the screen characteristics; and the current data whic'h is 
contained on the screen are placed at the high address end of RAM. .The 
bottom of this region defines the end of the "free memory* 1 region and 
its location is a function of the screen mode currently in effect. A 
pointer in the data base contains the address of the last available 
location below the screen region. 



Free memory region 

The free memory region is all that RAM between the end of the boot 
region and the start of the screen region. The outer level application 
is responsible for managing the free memory region. See sec tion 4 for 
more details. * " ^ 

r? 

Cartridges A and B ^ I5 J^ h Hl 

There are two 8K regions reserved for plug-in cartridges. Cartridge B, 
which is the right hand cartridge slot found only in the ATARI 800 
Personal Computer System, has been allocated memory addresses 8000 
through 9FFR while cartridge A, which is the left-hand cartridge slot 
in the ATARI 800 computer console, and is the only slot in the ATARI 
400 computer console, has been allocated memory addresses AOOO through 
BFFF and optionally 8000 through BFFF, for 16K cartridges. If a RAM 
module is plugged into the last slot such as to overlay any of these 
addresses, the RAM takes precedence as long as a cartridge is not 
inserted. However, if a cartridge is inserted, it will disable the 
entire conflicting RAM module in the last slot in 8K increments 



Mapped I/O 

The 6502 performs input/output operations by addressing the external 
support chips as memory; some chip registers are read/write while 
others are read only or write only (the ATARI Personal Computer System 
HARDWARE MANUAL gives descriptions of all of the external registers). 
While the entire address space from DOOO to D7FF has been allocated 
for I/O decoding, only the following sub-regions are used: 

D000-D01F = CTIA 
D200-D21F = POKEY 
D300-D31F = PIA 
D400-D41F = ANTIC 
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Resident OS and floating point package ROM 

The region from D800 through FFFF always contains the OS and the 
floating point package. To allow for the possibility that another/ but 
functionally compatible/ OS may be generated in the future/ care 
should be taken to avoid using any entry points that are not 
guaranteed not to move. The OS contains many vectored entry points at 
the end of the ROM and in RAM which will not move. The floating point 
package is not vectored/ but all documented entry points will be fixed 
(this means do not use undocumented routines found by scanning the 
listing!). A list of the fixed ROM vectors and entry points may be 
found in Appendix J. 

Central data base description 



Discussion of organization of this section. 

There are a large number of variables in the OS data base/ most of 
which have some relevance to the user/ either for control or debug 
purposes. This section provides detailed information for those 
variables which can be altered by the user in meaningful ways and to 
provide at least a narrative description of the remaining variables. 
One major problem/ when dealing with this many variables/ is how to 
present the information so that it is accessible to the user in the 
different contexts in which the user may work. This manual attempts to 
solve that problem by providing a multiple access scheme/ in which 
several lookup tables are provided/ all of which reference a common 
set of narratives that is itself ordered by function. 

In order to provide a means of referencing the variable descriptions/ 
the variable descriptions are each provided with a label consisting of 
a single letter followed by a number (e.g. A4/ B13/ etc. ). A different 
letter is assigned for each major functional area being described/ and 
the numbers are assigned sequentially within each functional area. 
This label just described will be reserved to as a VID (variable 
identifier) throughout the remainder of this document. Those var 
iables which are not concidered to be of interest to any user are 
flagged with an asterisk ('*') after their names. 

The database lookup tables provided are: 

1. Functional grouping — index to the function narrative and 
descriptions of variables/ giving VID and variable name. 

For more information, see Appendix K. 
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4 



FUNCTIONAL INDEX TO DATABASE VARIABLE DESCRIPTIONS 



A. Memory configuration 
Al MEMLO 
A2 MEMTOP 
A3 APPMHI 
A4 RAMTOP* 
A5 RAMSIZ 



B. Text/graphics screen 

Cursor control 
Bl CRSINH 
B2 ROWCRS, COLCRS 
B3 OLDROW, OLDCOL 
B4 TXTROW, TXTCOL 

Screen margins 
B5 LMARGN 
B6 RMARGN 

Color control 

B7 PCOLRO - PC0LR3 
B8 COLORO - C0L0R4 

Text scrolling 
B9 SCRFLG* 

Attract mode 
BIO ATRACT 
Bll COLRSH* 
B12 DRKMSK* 

Tab b ing 

B13 TABMAP 

Logical text lines 
B14 LOGMAP* 
B15 LOGCOL* 

Split screen 
B16 BOTSCR* 

FILL/DRAW function 
B17 FILDAT 
B18 FILFLG* 
B19 NEWROW*, NEWCOL* 
B20 H0LD4* 
B21 ROWINC*, COLINC* 
B22 DELTAR*, DELTAC* 
B23 COUNTR* 
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B24 ROWAC#, COLAC* 
B25 ENDPT* 

Displaying control characters 

Escape (display following control char) 
B26 ESCFLG# 

Display control characters mode 
B27 DSPFLG 

Bit mapped graphics 
B28 DMASK* 
B29 SHFAMT* 



Internal working variables 



B30 


HOLD1* 


B31 


H0LD2* 


B32 


H0LD3* 


B33 


TMPCHR* 


B34 


DSTAT* 


B35 


DINDEX* 


B36 


SAVMSC 


B37 


OLDCHR* 


B38 


OLDADR* 


B39 


ADRESS* 


B40 


MLTTMP /OPNTMP / TOADR* 


B41 


SAVADR /FRMADR* 


B42 


BUFCNT* 


B43 


BUFSTR* 


B A- A 


SWPFLG* 


B45 


INSDAT* 


B46 


TMPROW*, TMPCOL* 


B47 


TMPLBT* 


B48 


SUBTHP* 


B49 


T INDEX *■ 


B50 


BITMSK* 


B51 


LINBUF* 


B52 


TXTMSC 


B53 


TXTOLD* 



Internal character code conversion 
B54 ATACHR 
B55 CHAR* 



C. Disk handler 
CI BUFADR* 
C2 DSKTIM* 
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D. Cassette (part in SIO part in handler) 



baud 


rate determination 


Dl 


CBAUDL*, CBAUDH* 


D2 


TIMFLG* 


D3 


TIMER 1#, TIMER2* 


D4 


ADDCOR* 


D5 


TEMPI* 


D6 


TEMP3* 


D7 


SAVIO* 



Cassette mode 
D8 CASFLG* 

Cassette buffer 
D9 CASBUF* 
DIO BLIM* 
Dll BPTR* 

Internal ujorkina variables 
D12 FEOF* 
D13 FTYPE* 
D14 WMODE* 
D15 FREQ* 



E. Keyboard 

Key reading and debouncing 
El CHI* 
E2 KEYDEL* 
E3 CH 

Special functions 

Start/stop 
E4 SSFLAG 

C BREAK 3 

E5 BRKKEY 

SHIFT/CONTROL lock 
E6 SHFLOK 
E7 HOLDCH* 

Auto-repeat 
EB SRTIMR* 

Inverse video 
E9 INVFLG 

Console switches (SELECT, START & OPT ION ) 
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F. Printer 

Printer buffer 

Fl PRNBUF* 
F2 PBUFSZ* 
F3 PBPNT* 

Internal working variables 
F4 PTEMP* 
F5 PTIMOT* 



G. Central I/O routine <CIO) 

User call parameters 

Gl IOCB 
G2 ICHID 
G3 ICDNO 
G4 ICCOM 
G5 ICSTA 
G6 ICBAL, ICBAH 
G7 ICPTL, ICPTH 
G8 ICBLL, ICBLH 
G9 ICAX1, ICAX2 
GIO ICSPR 

Device status 
Gil DVSTAT 

Device Table 
G12 HATABS 

CIO/handler interface parameters 

G13 ZIOCB (IOCBAS) 

G14 ICHIDZ 

G15 ICDNOZ 

G16 ICCOMZ 

G17 ICSTAZ 

G18 ICBALZ, ICBALH 

G19 ICPTLZ, ICPTHZ 

G20 ICBLLZ. ICBLHZ 

G21 ICAX1Z, ICAX2Z 

G22 ICSPRZ < ICIDNO, CIOCHR > 

Internal working variables 
G23 ICCOMT# 
G24 ICIDNO* 
G25 CIOCHR* 
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H. Serial I/O routine (SIO) 



User call parameters 
HI DCB control block 



H2 


DDEVIC 


H3 


DUN IT 


H4 


DCOMND 


H5 


DSTATS 


H6 


DBUFLO, DBUFHI 


H7 


DTIMLO 


H8 


DBYTLO, DBYTHI 


H9 


DAUX1, DAUX2 



Bus sound control 
HIO SOUNDR 

Serial bus control 

Retry logic 
Hll CRETRY* 
H12 DRETRY* 

Ch ec k sum 

H13 CHKSUM* 
H14 CHKSNT* 
HI 5 NOCKSM* 

Data buffering 

General buffer control 

H16 BUFRLO*, BUFRHI* 
H17 BFENLO*/ BFENHI* 

Command frame output buffer 
H18 CDEVIO 
H19 CCOMND* 
H20 CAUX1*, CAUX2* 

Receive/transmit data buffering 
H21 BUFRFL* 
H22 RECVDN* 
H23 TEMP* 
H24 XMTDON* 

SIO timeout 
H25 TIMFLG* 
H26 CDTMV1* 
H27 CDTMA1* 

Internal working variables 
H28 STACKP* 
H29 TSTAT* 
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H30 ERRFLG* 
H31 STATUS* 
H32 SSKCTL* 



ATARI controllers 

Joysticks 

Jl STICKO - STICK3 
J2 STRIGO - STRIG3 

Paddles 

J3 PADDLO - PADDL7 
U4 PTRIGO - PTRIG7 

Light pen 
U5 LPENH 
J6 LPENV 
U7 STICKO 

Driving controllers 
US STICKO - STICK3 
J9 STRIGO - STRIG3 



K. Disk file manager 
Kl FMSZPG* 
K2 ZBUFP* 
K3 ZDRVA* 
K4 ZSBA* 
K5 ERRNO* 



L. Disk utilities (DOS) 
LI DSKUTL* 



M. Floating point package 
Ml FRO 
M2 FRE* 
M3 FR1 
M4 FR2* 
M5 FRX* 
M6 EEXP* 
M7 NSIGN* 
MS ESIGN# 
M9 FCHRFLG* 
MIO DIGRT* 
Mil CIX 
M12 INBUFF 
M13 ZTEMP1-* 
M14 ZTEMP4* 
Ml 5 ZTEMP3* 
Ml 6 FLPTR 
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M17 

Mi/ 


FPTR2* 


MIS 


LBPR1* 


Ml Q 


1 nppox 
Lur nc 1 ' 


M20 


LBUFF 


M21 


PLYARG* 


M22 


FPSCR/FSCR* 


M23 


FPSCR1/FSCR1* 


M24 


DEGFLG/RADFLG* 



N. Power up & CS RESET] 
RAM sizing 

Nl RAMLO*. TRAMSZ* 
N2 TSTDAT* 



Disk 


/cassette 


N3 


DOSINI 


N4 


CKEY* 


N5 


CASSBT* 


N6 


CASINI 


N7 


BOOT?* 


N8 


DFLAGS* 


N9 


DBSECT* 


N10 BOOTAD* 



Environmental control 
Nil COLDST* 
N12 DOSVEC 

CS RESET] 

N13 WARMST 



P. Interrupts 
PI CRITIC 
P2 POKMSK 

System timers 

Real-time clock 
P3 RTCLOK 

System timer 1 
P4 CDTMV1 
P5 CDTMA1 

System timer 2 
P6 CDTMV2 
P7 CDTMA2 

System timers 3-5 

P8 CDTMV3/ CDTMV4, CDTMV5 
P9 CDTMF3, CDTMF4/ CDTMF5 
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RAM interrupt vectors 

NMI interrupt vectors 
PIO VDSLST 
Pll WBLKI 
P12 WBLKD 

IRQ interrupt vectors 
P13 VIMIRQ 
P14 VPRCED 
PI 5 V INTER 
P16 VBREAK 
P17 VKEYBD 
P18 VSERIN 
P19 VSEROR 
P20 VSEROC 

P21 VTIMR1, VTIMR2, VTIMR4 

Hardware register updates 
P22 SDMCTL* 
P23 SDLSTL*, SDLSTH* 
P24 GPRIOR* 
P25 CHACT* 
P26 CHBAS 
P27 PCOLRx, COLOR x 

Internal working variable 
P28 INTEMP* 



R. User areas 

Rl (unlabeled) 
R2 USAREA 



S. Unused (spare) bytes 

51 HOLDS 

52 CSTAT 

53 DUNUSE 

54 TEMP2 

55 TMPX1 

56 DSKFMS 
S7-S15 (unlabeled) 
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Memory dynamics 

The free memory region is the area between the end of the boot region 

and the start of the screen region* and as such/ its limits are 

variable. The bottom of the free region is defined by the content of 
the variable MEMLO C02E73* and the top of the region is defined by the 

content of the variable MEMTOP C02E53. The conditions which cause the 

setup or alteration of these variables are now discussed. 



System initialization process 

When the system is powered-up* the extent of the lowest block of 
contiguous RAM is determined and the limits are saved. The Screen 
Editor is then opened* thus setting a new (and lower) value in MEMTOP. 
Then* as discussed in section 7* disk or cassette booted software 
might be brought into memory* which would probably set a new (and 
higher) value in MEMLO. When the application program finally gets 
control* MEMLO and MEMTOP will define the maximum amount of free 
memory available at that time* however* that amount may later decrease 
further* as described in the next paragraph. 



Changing screen modes 

The user may, at any time* command the Display handler to change 
screen modes. In most cases this will involve a change in the memory 
required for the display list and display data* and hence* will change 
the value of MEMTOP. Appendix H indicates the amount of memory 
required for each of the screen modes. 

In order to allow the user to protect the portion of free memory space 
that he is using from being overwritten as a result of a screen mode 
change* the variable APPMHI COOOE3 is interpreted by the Display 
handler as containing the address below which MEMTOP may not extend. 
If* as a result of a screen mode change* the Display handler 
determines that the screen memory would extend below APPMHI* then the 
screen is setup for mode 0* MEMTOP is updated and an error status is 
returned to the user* otherwise the desired mode change is effected 
and MEMTOP is updated. 
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5 I/O subsystem 



Introduction 



This section discusses the I/O subsystem of the operating system. The 
I/O subsystem is a collection of routines which allows the user to 
access peripheral and local devices at a number of different levels* 
all higher than that of accessing the device hardware registers 
directly. The routine of interest to most users is CIO (Central I/O 
utility), which provides the highest level, device independent access 
to devices. The next level down would be communication with the device 
handlers, followed by use of the SIO (Serial I/O bus utility) routine, 
which is the bottom level general I/O routine in the OS Any lower 
level access to a device would involve the direct reading and writing 
of the hardware registers associated with the device. 

The basic unit of input/output is the data byte, which can contain 
either "binary" (non-text) information or encoded text information. 
The text encoding scheme supported by the OS is called ATASCII, the 
name of which is derived from the words 'ATARI ASCII'. Most ATASCII 
codes are the same as ASCII, with the primary deviations being the 
control codes. Appendix D shows the ATASCII character set, and 
Appendices E, F and G show device specific implementations for the 
display, keyboard and printer. 

* 

The structure of the I/O subsystem is shown on the following page. 
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I/O SUBSYSTEM FLOW DIAGRAM 
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Where: shows a control path. 

shows the data structure required for a path. 

Note the following: 

1. The Keyboard/Display /Screen Editor handlers don't use SIO 

2. The Disk handler is not callable directly from CIO. 

3. The DCB is shown twice in the diagram. 



Central I/O Utility (CIO) 

The Central I/O Utility (CIO) provides the user with a single 
interface with which to access all of the system peripheral devices 
in a device independent manner. The minimum unit of data transfer i 
the data byte* with multiple byte transfers also supported. All I/O 
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operations are performed on a "return to user when complete" basis; 
there is no way to initiate concurrent "overlapped" I/O processes. 

I/O is organized by "files"* where a file is a sequential collection 
of data bytes. A file may or may not contain textual data and it may 
or may not be organized by "records"/ where a record is a contiguous 
group of bytes terminated by an EOL (End of Line) character. Some 
files are synonymous with a device (as with the printer and the Screen 
Editor)/ while other devices may contain a multiplicity of files/ each 
with a unique name (as with the floppy disk). 

CIO will allow the user to access up to eight independent device/files 
at one time; there being that many I/O Control Blocks (IOCBs) in the 
system. Each of the IOCBs may be assigned to control any desired 
device/file/ as there are no preferred assignments/ except that IOCB 
#0 is assigned to the Screen Editor at power up and CS/RESET3. 

In order to access a peripheral/ the user must first setup an IOCB for 
the OPEN command/ which supplies the system name for the device to be 
accessed (e.g. 'K: ' for the keyboad/ 'P: ' for the printer, 'D: STARS ' 
for a disk file named 'STARS'/ etc. ). The user then calls CIO/ telling 
it which IOCB to use to find the OPEN information. CIO attempts to 
find the specified device/file and returns a status byte indicating 
the success of the search. If the specified device/file can be found 
by CIO/ then CIO stores control information in the IOCB and that IOCB 
is now used for as long as that file is OPEN. 

Once a file is OPEN/ it can then be accessed using data read or data 
write types of commands; in general/ reading may proceed until there 
is no more data to read (End of File) and writing may proceed until 
there is no more medium to store data on (End of Medium)/ although 
neither reading nor writing need proceed to that point. The reading 
and writing of data generally occurs into and out of user supplied 
data buffers (although a special case allowing single byte transfers 
using the 6502 A register is provided). 

When there are no more accesses to be performed on an OPEN 
device/file* the CLOSE operation is performed by the user. This 
accomplishes two functions: 1) it terminates and makes permanent an 
output file (essential for disk and cassette) and 2) it releases that 
IOCB to be used for another I/O operation. 



CIO Design Philosophy 

The CIO utility was designed specifically to meet the following design 
criteria. 

The transfer of data is device independent. 

By te-at-a-t ime/ multiple byte and record aligned accesses are 
supported. 

Multiple device/files can be accessed concurrently. 
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Error handling is largely device independent. 

New device handlers may be added without altering the system ROM. 
DEVICE INDEPENDENCE 

CIO provides device independence by having a single entry point for 
all devices (and for all operations) and by having a device 
independent calling sequence. Once a device/file is OPENed, data 
transfers occur with no regard to the actual device involved. Uniform 
rules for handling byte and record oriented data transfers allow the 
actual device storage block sizes to be transparent to the user. 

DATA ACCESS METHODS 

Two file access methods are supported by CIO: byte aligned and record 
a 1 i gned. 

Byte aligned accesses allow the user to treat the device/file as a 
sequential byte stream; any number of bytes may be read or written and 
the following operation will continue where the prior one left off. 
Records are of no consequence in this mode, and reads or writes may 
encompass multiple records if desired. 

Record aligned accesses allow the user to deal wit-h the data stream at 
a higher level, that of the data record or "line of text". Each and 
every write operation creates a single record (by definition), and 
each read operation assures that the following read operation will 
start at the beginning of a record. Record aligned accesses may not 
deal with portions of more than one record at a time. Record aligned 
accesses are useful only with text data or with binary data guaranteed 
not to contain the EOL character ($9B) as data. 

Note that any file may be accessed using the byte aligned access 
method, regardless of how the file was created. But not all files may 
be successfully read using record aligned accesses; the file must 
contain EOL characters at the end of each record and at no other 
place. 

MULTIPLE DEVICE/FILE CONCURRENCY 

Up to eight device/files may be accessed concurrently using CIO, each 
operating independently of the others. 

UNIFIED ERROR HANDLING 

All error detection and recovery occurs within the CIO subsystem and 
the status information that reaches the user is in the form of a 
status byte for each device/file. As much as possible, error codes are 
device independent (see Appendix B). 



DEVICE EXPANSION 
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Devices are known by one character names such as 'K' or 'P'* and a 
number of device handlers are part of the resident system ROM. 
However/ additional device handlers may be added to the system using 
the RAM resident Device Table; this is normally done at power up time 
with the disk boot process/ but may be done at any point in time. 



CIO calling mechanism 



The primary element in performaing I/O using CIO is an Input/Output 
Control Block (IOCB). There are eight IOCBs in the system, arranged 
linearly in RAM as shown below. 



! IOCB O I 
\ IOCB 1 ! 



low address C03403 



i IOCB 6 ! 



I IOCB 7 J 



+ high address 



One IOCB is required for each OPEN device/file and any IOCB may be 
used to control any device/file; although IOCB O is normally assigned 
to the Screen Editor (E: ). A typical I/O operation is performed by 
having the user: 1) insert appropriate parameters into an IOC3 of his 
chosing* 2) put the IOCB number times 16 into the 6502 X register and 
3) JSR to the CIO entry point CIOV CE4563. CIO will return to the user 
when the operation is complete or if an error was encountered; the 
status of the operation will be in the IOCB used as well as in the 
6502 Y register; in addition/the 6502 conditions codes will reflect 
the value in the Y register. . In some cases a data byte will be in the 
6502 A register. The X register will remain unchanged for all 
operations and conditions. An example is shown below: 



I0CB2X 



$20 



; INDEX FOR IOCB #2. 



LDX 
JSR 



BMI 



#I0CB2X 
CIOV 

#0; (opt i ona 1 ) 
ERROR 



Each IOCB is sixteen bytes long, in which some bytes are user 
alterable and some are for use by CIO and/or the device handl 
of the IOCB bytes will now be described/ and the system equate 
name and memory address for each will be given. 



Eac h 
file 



HANDLER I.D. — ICHID C0340D 
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The handler I.D. is an index into the system Device Table (see section 
9 > and is not user alterable. This byte is set by CIO as the result 
of an OPEN command and is left unchanged until the device/file is 
CLOSEd, at which time CIO a/ill set the byte to $FF. 

DEVICE NUMBER — ICDNO C 0341 3 

The device number is provided by CIO as the result of an OPEN command 

and is not user alterable. This byte is used to distinguish between 

multiple devices of the same type, such as 'Dl. ' and 'D2: '. 

COMMAND BYTE — ICCMD C03423 

The command byte is set by the user and tells CIO which of its 
repertoire of commands is to be performed. The commands and their 
command byte values will be detailed in section 5.2.3. This byte is 
not altered by CIO. 

STATUS — ICSTA C03433 

The status byte is used by CIO to convey operation status to the user; 
it is updated as a result of each and every CIO call. The most 
significant (sign) bit is a one for error conditions and zero for 
non-error conditions, and the remaining bits represent an error 
number. See Appendix B for a list of status codes. 

BUFFER ADDRESS — ICBAL C03443 & ICBAH C03453 

This two byte pointer is set by the user and is not altered by CIO. 
The pointer contains the address of the beginning (low address) of a 
buff er which is used to: 1) contain data for read and write operations 
and 2) contain the device/filename specification for the OPEN command. 
The pointer may be altered at any time by the user. 

PUT ADDRESS — ICPTL C03463 & ICPTH C03473 

This two byte pointer to the handler's PUT CHARACTER entry point (- 1) 
is set by CIO at OPEN time; this was provided as an accommodation to 
the people writing the BASIC cartridge and has no legitimate use in 
the system. This variable is set to point to CIO's "IOCB not OPEN" 
routine on CLOSE, power up and CS/RESET3. 

BUFFER LENGTH/BYTE COUNT — ICBLL C 0348 3 & ICBLH C03493 

This two byte count is set by the user to indicate the size of the 
data buffer pointed to by ICEAL and ICBAH for read and write 
operations; it is not required for OPEN. After each read or write 
operation, CIO will set this parameter to the number of bytes actually 
transferred into or out of the data buffer. For record aligned 
accessed, the record length may well be less than the buffer length. 
Also an end of file condition or an error may cause the byte count to 
be less than the buffer length. 

AUXILLIARY INFORMATION — ICAX1 C034A3 & ICAX2 C034B3 
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These two bytes are set by the user and contain information which is 
used by the OPEN command process and/or is device dependent. 

For OPEN/ two bits of ICAX1 are always used to specify the OPEN 
direction as shown below# where R is set to 1 for input (read) enable 
and W is set to 1 for output (write) enable. 

7 3 2 0 

— I- — i — +~ + 

i i i i i W i PC i i i 
H I i I I i I » H 

ICAX1 is not altered by CIO and should not be altered by the user once 
the device/file is OPEN. 

The remaining bits of ICAX1 and all of ICAX2 contain only device 
dependent data and are explained in section 5:Device specific information. 

REMAINING BYTES ( ICAX3-ICAX6 ) 

The four remaining bytes are reserved for use by the handler 
processing the I/O command for CIO. There is no fixed use for these 
bytes and they are not user alterable except as specified by the 
particular device descriptions in sectibn 5.3. These bytes will be 
referred to as ICAX3/ ICAX4, ICAX5 and ICAX6/ although there are no 
equates for those names in the OS equate file. 



CIO functions 

There are eight basic functions that are supported by all of the 
system handlers/ subject to restrictions based upon the 
direction of data transfer (e.g. one cannot read data from the 
printer). The basic functions are: OPEN, CLOSE/ GET CHARACTERS/ 
PUT CHARACTERS/ GET RECORD/ PUT RECORD/ GET STATUS and SPECIAL. 
Other# device specific/ commands are also supported by CIO and 
are described in section 5:Device specific information. 



OPEN — Assign device/filename to IOCB and ready for access. 

Before a device/file may be accessed/ it must be OPENed; this process 
links a specific IOCB to the appropriate device handler/ initializes 
the device/file/ initializes an CIO control variables, and passes 
device specific options to the device handler. 

The following IOCB parameters are set by the user prior to calling CIO 
for an OPEN operation: 

COMMAND BYTE = *03 

BUFFER ADDRESS = pointer to a device/filename specification (see 
section 5: Device/filename specification.) 
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AUX1 = OPEN direction bits, plus device dependent information. 

AUX2 = device dependent information. 

After an OPEN operation, CIO will have altered the following IOCB 
parameters : 

HANDLER I.D. = index to the system Device Table; this is used 
only by CIO and must not be altered by the user. 

DEVICE NUMBER = device number taken from the device/ filename 
specification and must not be altered by the user. 

STATUS » result of OPEN operation; see Appendix B for a list of 
the possible status codes. In general/ a negative status will 
indicate a failure to OPEN properly. 

PUT ADDRESS = pointer to the PUT CHARACTERS routine for the 
device handler just OPENed. *** It is recommended that this 
pointer not be used 



CLOSE — Terminate access to device/file and release IOCB. 

After the user is through accessing a given device/file/ the CLOSE 
command is issued. This process completes any pending data writes, 
goes to the device handler for any device specific actions and then 
releases the IOCB. 



The following IOCB parameter is set by the user prior to calling CIO 

COMMAND BYTE = *0C 

The following IOCB parameters are altered by CIO as a result of the 
CLOSE operation: 

HANDLER I.D. = *FF 



STATUS = Result of CLOSE operation. 

PUT ADDRESS - pointer to "IOCB not OPEN" routine. 



GET CHARACTERS — Read n characters (byte aligned access). 

The specified number of characters are read from the device/file to 
the user supplied buffer. EOL characters have no termination feature 
when using this function; there may be no EOL, or many EOLs, in the 
buffer after operation completion. There is a special case provided 
that passes a single byte of data in the 6502 A register when the 
buffer length is set td zero. 

The following IOCB parameters are set by the user prior to calling 

CIO: 
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COMMAND BYTE m %07 

BUFFER ADDRESS ■ pointer to data buffer. 

BUFFER LENGTH = number of bytes to read; if this is zero, the 
data will be returned in the 6502 A register only. 

The following IOCB parameters are altered by CIO as a result of the 
GET CHARACTERS operation: 

STATUS * result of GET CHARACTERS operation. 

BYTE COUNT/BUFFER LENGTH « number of bytes read to the buffer. 
The BYTE COUNT will always equal the BUFFER LENGTH except uihen an 
error or an end-of-file condition occurs. 

PUT CHARACTERS Write n characters (byte aligned access). 

The specified number of characters are written from the user supplied 
buffer to the device/file. EOL characters have no buffer terminating 
properties, although they have their standard meaning to the 
device/file receiving them; no EOLs are generated by CIO. There is a 
special case that allows a single character to be passed to CIO in the 
6502 A register if the buffer length is zero. 

The following IOCB parameters are set by the user prior to initiating 
the PUT CHARACTERS operation: 

COMMAND BYTE = *0B 

BUFFER ADDRESS = pointer to data buffer. 

BUFFER LENGTH = number of bytes of data in buffer. 

The following IOCB parameter is altered by CIO as a result of the PUT 
CHARACTERS operation: 

STATUS ■ result of PUT CHARACTERS operation. 

GET RECORD — Read up to n characters (record aligned access). 

Characters are read from the device/file to the user supplied buffer 
until either the buffer is full or an EOL character is read and put 
into the buffer. If the buffer fills before an EOL is read, CIO 
continues reading characters from the device/file until an EOL is 
read, then puts an EOL at the end of the buffer, and sets the status 
to indicate that a truncated record was read. 

The following IOCB parameters are set by the user prior to calling 

CIO: 



COMMAND BYTE - *05 
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BUFFER ADDRESS = pointer to data buffer. 

BUFFER LENGTH = maximum number of bytes to read (including the 
EOL character). 



The following IOCB parameters are altered by CIO as a result of the 
GET RECORD operation: 

STATUS = result of GET RECORD operation. 

BYTE COUNT/BUFFER LENGTH = number of bytes read to data buffer; 
this may be less than the maximum buffer length. 



PUT RECORD — Write up to n characters (record aligned access). 

Characters are written from the user supplied buffer to the 
device/file until either the buffer is empty or an EOL character is 
written. If the buffer is emptied without writing an EOL character to 
the device/file, then CIO will send an EOL after the last user 
supplied character. 

The following IOCB parameters are set by the user prior to calling 
CIO: d 



COMMAND BYTE - *09 



BUFFER ADDRESS = pointer to data buffer. 

BUFFER LENGTH = maximum number of bytes in buffer. 

The following IOCB parameter is altered by CIO as a result of the PUT 
RECORD operation: 

STATUS = result of PUT RECORD operation. 



GET STATUS — Return device dependent status bytes 

i 

The device controller is sent a STATUS command, and the controller 
returns four bytes of status information which are stored in DVSTAT 
C02EA3. See the subsections of 5.3 for the status information returned 
by each device. 

The following IOCB parameters are set by the user prior to callina 
CIO: 



COMMAND BYTE = *OD 

BUFFER ADDRESS ■ pointer to a device/filename specification if 
the IOCB is not already OPEN; see the 
discussion of the implied OPEN option below. 
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After a GET STATUS operation, CIO will have altered the following 
parameters: 

STATUS = result of GET STATUS operation; see Appendix B for a 
list of the possible status codes. 

DVSTAT = the four byte response from the device controller. 



SPECIAL — Special function 

Any COMMAND BYTE value greater than *0D is treated by CIO as a special 
case. Since CIO does not know what the function is, CIO transfers 
control to the device handler for complete processing of the 
operation. 

The following IOCB parameters are set by the user prior to calling/ 
CIO: 

COMMAND BYTE > *OD 

BUFFER ADDRESS ■ pointer to a device/filename specification if 
the IOCB is not already OPEN; see the 
discussion of the implied OPEN option below. 

Other IOCB bytes may be setup, depending upon the specific 
SPECIAL command being performed. 

After a SPECIAL operation, CIO will have altered the following 
parameters: 

STATUS = result of SPECIAL operation; see Appendix B for a list 
of the possible status codes. 

Other bytes may be altered, depending upon the specific SPECIAL 
command. 

The device specific sections in 5.3 will detail the individual SPECIAL 
commands supported by the system. 

Implied OPEN option 

The GET STATUS and SPECIAL commands are treated specially by CIO; they 
may use an already OPEN IOCB to initiate the process or they may use 
an unOPENed IOCB. If the IOCB is unOPENed, then the BUFFER ADDRESS 
must contain a pointer to a device/filename specification, just as for 
the OPEN command; CIO will then OPEN that IOCB, perform the specified 
command and then CLOSE the IOCB again. 
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Device/filename specification 

As part of the OPEN command/ the IOCB buffer address parameter points 
to a device/filename specification/ which is a string of ATASCII 
characters in the following format: 

<spec if ication> : : = <device>C<number>3: C<f i 1 ename>3<eo 1> 

<device> = C i DIE! KIP IRIS 
<number> ::= 1I2I3I4I5I6I7I8 

<filename> has device dependent characteristics. 

<eol> : : = *9B 

The following devices are supported at this writing: 
C = Cassette drive 

Dl through D8 ■ Floppy diskette drives * 

E = Screen Editor 

K = Keyboard 

P = 40 column printer 

P2 = 80 column printer * 

Rl through R4 = RS-232-C interfaces * 

S = Screen display 

Devices flagged by asterisks ('*') are supported by non-resident 
hand ler s. 

If <number> is not specified/ it is assumed to be 1. 

The following examples show valid device/filename specifications: 

i 

C: Cassette 

D2: BDAT File "BDAT" on disk drive #2 

D: HOLD File "HOLD" on disk drive #1 

K: Keyboard 

I/O example 

The example provided in this section illustrates a simple example of 
an I/O operation using the CIO routine. 

This code segment illustrates the simple example of reading 
text lines (records) from a disk file named "TESTER" on disk 
drive #1. All symbols used are equated within the program 
although many of the symbols are in the OS equate file. 

The program performs the following steps: 

1. OPENs the file 'Dl: TESTER' using IOCB #3. 

2. Reads records until an error or EOF is reached. 

3. CLOSEs the file. 

I/O EQUATES 
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EOL= 


*9B 


• 

f 


END OF LINE CHARACTER. 


I0CB3= 


*3Q 


• 


IOCB #3 OFFSET (FROM IOCB #0). 


ICHID= 


*0340 


• 

t 


(HANDLER I.D. — SET BY CIO). 


ICDNO= 


ICHID+1 


• 


(DEVICE # — SET BY CIO). 


ICCOM= 


ICDNO+1 


• 


COMMAND BYTE. 


ICSTA= 


ICCOM+1 


* 

t 


STATUS BYTE — SET BY CIO. 


ICBAL= 


ICSTA+1 


m 

1 


BUFFER ADDRESS (LOW). 


ICBAH= 


ICBAL+1 


• 

1 


BUFFER ADDRESS (HIGH). 


ICPTL= 


ICBAH+1 






ICPTH= 

X \— r I III 


TCPTL+1 






ICBLL= 


ICPTH+1 


• 


BUFFER LENGTH (LOW). 


ICBLH= 


ICBLL+1 


• 


BUFFER LENGTH (HIGH). 


ICAX1= 


ICBLH+1 


• 


AUX 1. 


ICAX2= 


ICAX1+1 


• 

• 
# 


AUX 2 


OPEN= 




• 


□PEN COMMAND. 


QFTRFf = 
*j? c_ i r\ l_ ~ 


W 


i 




CLOSE= 


*OC 


■ 


CLOSE COMMAND. 

* 


OREAD= 


*04 


• 


□PEN DIRECTION = READ. 


OWRIT- 


*oe 


• 

* 


OPEN DIRECTION = WRITE. 


EOF= 


*88 


i 


END OF FILE STATUS VALUE. 


C I OV= 


*E456 


• 


CIO ENTRY VECTOR ADDRESS. 



I 



INITIALIZE THE IOCB FOR FILE "OPEN". 



LDX 


#10CB3 


LDA 


#0PEN 


STA 


ICCOM, X 


LDA 


#NAME 


STA 


I CBAL/ X 


LDA 


#NAME/256 


STA 


ICBAH, X 


LDA 


#OREAD 


STA 


ICAX1. X 


LDA 


#0 


STA 


ICAX2, X 



i SETUP TO ACCESS IOCB #3 
; SETUP OPEN COMMAND. 



; SETUP BUFFER POINTER TO 
; ... POINT TO FILENAME. 



SETUP FOR OPEN READ 



CLEAR AUX 2. 



"OPEN" THE FILE 
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JSR 
BPL 



CIOV 
TPIO 



PERFORM "OPEN" OPERATION. 
YES — STATUS WAS POSITIVE. 



JMP 



ERROR 



NO — "OPEN" PROBLEM. 



SETUP TO READ A RECORD. 



TPIO 



LDA 

STA 



#CETREC 
ICCOM, X 



; SETUP "GET RECORD" COMMAND 



LDA 
STA 
LDA 
STA 



#BUFF 
ICBAL, X 
#BUFF/256 
ICBAH, X 



; SETUP DATA BUFFER POINTER. 



READ RECORDS. 



LOOP 



LDA 
STA 
LDA 
STA 

JSR 
BMI 



#BUFFSZ 
ICBLL, X 
#BUFFSZ/256 
ICBLH, X 

CIOV 
TP20 



SETUP MAX RECORD SIZE . . 
. . . PRIOR TO EVERY READ. 



READ A RECORD. 

NO — MAY BE END OF FILE 



A RECORD IS NOW IN THE DATA BUFFER "BUFF". IT IS TERMINATED BY 
AN EOL CHARACTER, AND THE RECORD LENGTH IS IN "ICBLL" & " ICBLH" 
THIS EXAMPLE WILL DO NOTHING WITH THE RECORD JUST READ. 



JMP 



LOOP 



i READ NEXT RECORD. 



NEGATIVE STATUS ON READ — CHECK FOR END OF FILE. 



TP20 



CPY 


#EOF 


BNE 


ERROR 


LDA 


#CLOSE 


STA 


ICCOM, X 


JSR 


CIOV 


HLT 





i END OF FILE STATUS? 
; NO — ERROR. 

j YES — CLOSE FILE. 



; CLOSE THE FILE. 

; *#* END OF PROGRAM 



DATA REGION OF EXAMPLE PROGRAM 
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NAME . BYTE "Dl : TESTER " , EOL 

BUFFSZ= 80 ; 80 CHARACTER RECORD MAX 

(INCLUDES EOL). 

BUFF= * ; READ BUFFER. 

*= *+BUFFSZ 

. END 



Device specific information 

This section provides device specific information regarding device 
handlers that interface to CIO. 



Keyboard handler (K: ) 

The Keyboard device is a read only device with a handler that supports 
the following CIO functions: 

OPEN 
CLOSE 

GET CHARACTERS 
GET RECORD 

GET STATUS (null function) 
The Keyboard handler may produce the following error statuses: 
*80 — CBREAK3 key abort. 

$88 — End-of-file (produced by pressing CTRL-3). 

The Keyboard handler is one of the resident handlers* and therefore 
has a set of device vectors starting at location E420/ as described 
further in section 5. 

The keyboard can produce any of the 256 codes in the ATASCII character 
set as shown in Appendix F. Note that a few of the keyboard keys do 
not generate data at the Keyboard handler level; these keys are 
described below: 

The ATARI key toggles a flag which enables/disables the 
inversion of bit-7 of each data character read. The Screen 
Editor editing keys are exempted from such inversion, 
however. 

The CAPS key provides three functions: 
SHIFT-CAPS — Alpha caps lock. 
CTRL-CAPS — Alpha CTRL lock. 
CAPS — Alpha unlock. 
The system powersup and ES/RESET3s to the Alpha caps lock 
option. 



C/!\3 - 



CAPS - 
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Some key combinations are ignored by the handler, such as CCTRL3-4 
through CCTRL3-9, CCTRL3-0/ CCTRL3-1, [CTRL]-/ and all key 
combinations in which the CSHIFT3 and ECTRL3 keys are depressed 
simultaneously. 

The CCTRL3-3 key generates an EOL character and returns EOF status. 
The CBREAK3 key generates an EOL character and returns BREAK status. 



CIO function descriptions 

The device specific characteristics of the standard CIO functions 
(described earlier in this section) are detailed below: 

OPEN 

The device name is 'K'# and the handler ignores any device number and 
filename specification! if included. 

There are no device dependent option bits in AUX1 or AUX2. 
CLOSE 

No special handler actions. 
GET CHARACTERS and GET RECORD 

The handler returns the ATASCII key codes to CIO as they are entered, 
with no facility for editing. 

GET STATUS 

The handler does nothing but set the status to *01. 



Theory of operation. 

Everytime a keyboard key is pressed/ an IRQ interrupt is generated as 
discussed in section 6 and is vectored to the Keyboard handler's 
interrupt service routine as shown later in section 6. The key code 
for the key pressed is then read and stored in data base variable CH 
C02FC3; this occurs whether or not there is an active read request to 
the Keyboard handler/ thus effecting a one byte FIFO for keyboard 
entry. See section 4 (E8) for a discussion of the auto-repeat feature. 

Whenever there is an active read request for the Keyboard handler, the 
handler monitors the CH variable for not containing the value $FF 
(empty state). When CH shows non-empty/ the handler takes the key code 
from CH and sets CH to $FF again. The key code byte obtained from CH 
is not ATASCII code and has the following form: 
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7 0 

H 1 1 1 1- — I- — I 1 h 

!C!S! key code ! 

Where: C » 1 if the CTRL key is pressed. 

S = 1 if the SHIFT key is pressed. 

The remaining 6 bits are the hardware key code. 

The key code obtained is then converted to ATASCII using the first of 
the following rules which applies: 

1. Ignore the code if the C & S bits are both set. 

2 If the C bit is set/ process the key as a CTRL code. 

3. If the S bit is set/ process the key as a SHIFT code. 

4. If CTRL lock is in effect/ process alpha characters as CTRL 
codes, all others as lower case. 

5. IF SHIFT lock is in effect/ process alpha characters as SHIFT 
codes/ all others as lower case. 

6. Else/ process as lower case character. 

Then/ if the resultant code is not a Screen Editor control code/ 
and if the video invert flag is set/ set bit-7 of the ATASCII 
code (causes inverse video when displayed). 

The keycode to ATASCII conversion table is shown on the next 
page. See also Appendix F. 
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KEYCODE TO ATASCII CONVERSION TABLE 



Key 


Key 


1. c. 


SHIFT 


CTRL 


Key 


Key 


I.e. 


SHIFT 


CT 


Code 


Cap 








Code 


Cap 








00 


L 


6C 


4C 


OC 


20 




2C 


5B 


00 


01 


J 


6A 


4A 


OA 


21 


SPACE 


20 


20 


20 


02 


• 


3B 


3A 


7B 


22 


• 


2E 


5D 


60 


03 










23 


N 


6E 


4E 


OE 


04 










24 










05 


K 


6B 


4B 


OB 


25 


M 


6D 


4D 


OD 


06 


+ 


2B 


5C 


IE 


26 


/ 


2F 


3F 


— 


07 


* 


2A 


5E 


IF 


27 


) : ( 








08 


0 


6F 


4F 


OF 


28 


R 


72 


52 


12 


09 










29 










OA 


P 


70 


50 


10 


2A 


E 


65 


45 


05 


OB 


U 


75 


55 


15 


2B 


Y 


79 


59 


19 


OC 


RET 


9B 


9B 


9B 


2C 


TAB 


7F 


9F 


9E 


OD 


I 


69 


49 


09 


2D 


T 


74 


54 


14 


OE 


— 


2D 


5F 


1C 


2E 


W 


77 


57 


17 


OF 


— 


3D 


7C 


ID 


2F 


Q 


71 


51 


11 


10 


V 


76 


56 


16 


30 


9 


39 


28 


— 


1 1 










31 










12 


c 


63 


43 


03 


32 


0 


30 


29 


— 


13 










33 


7 


37 


27 


— 


14 










34 


BACKS 


. 7E 


9C 


FE 


15 


B 


62 


42 


02 


35 


8 


3e 


40 


— 


16 


X 


78 


58 


18 




< 


3C 


7D 


7D 


17 


z 


7A 


5A 


1A 


37 


> 


3E 


9D 


FF 


18 


4 


34 


24 




38 


F 


66 


46 


06 


19 










39 


H 


68 


48 


08 


1A 


3 


33 


23 


9B* 


3A 


D 


64 


44 


04 


IB 


6 


36 


26 




3B 










1C 


ESC 


IB 


IB 


IB 


3C 


CAPS 








ID 


5 


35 


25 




3D 


G 


67 


47 


07 


IE 


2 


32 


22 


FD 


3E 


S 


73 


53 


13 


IF 


1 


31 


21 




3F 


A 


61 


41 


01 



* CCTRL1-3 returns EOF status. 



The inverse of this table (ATASCII to keystroke) is given in Appendix 
F. 
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Display handler (S: ) 

The Display device is a read/write device with a handler that supports 
the following CIO functions: 

OPEN 
CLOSE 

GET CHARACTERS 
GET RECORD 
PUT CHARACTERS 
PUT RECORD 

GET STATUS (null function) 

DRAW 
FILL 

The Display handler may produce the following error statuses: 

*S4 — Invalid special command. 
*8D — Cursor out of range. 
$91 — Screen mode > 11. 

$93 — Not enough memory for screen mode selected. 

The Display handler is one of the resident handlers; and therefore has 
a set of device vectors starting at location E410. 



Screen modes 

The display screen may be operated in any of 20 configurations (modes 

I through 8* with or without split screen/ plus modes 0 and 9 through 

II without split screen). Mode 0 is the text displaying mode and modes 
1 through 11 are all different graphics modes (although modes 2 and 3 
do display a subset of the ATASC 1 1 character set). Modes 9 through 11 
require a CTIA chip to be installed in place of the standard CTIA 
chip. 

TEXT MODE (mode 0) 

In text mode the screen is physically comprised of 24 lines of 40 
characters per line; however* the display area is limited by program 
alterable left and right margins which default to 2 and 39 (of a 
possible 0 and 39). 

A program controllable cursor shows the destination of the next 
character to be output. The cursor is visible as the inverted video 
representation of the current character at the destination position. 

The text screen data is organized internally as variable length 
logical lines; when the screen is cleared* the internal representation 
is 24 empty lines. As text is sent to the screen* each EOL marks the 
end of a logical line; or if more than 3 physical lines of text are 
sent* a logical line will be formed every 3 physical lines. The number 
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of physical lines used to comprise a logical line (1 to 3) is always 
the minimum required to hold the data for that logical line. 

The text screen "scrolls" upward whenever a text line at the bottom 
row of the screen extends past the right margin or a text line at the 
bottom row is terminated by an EOL. Scrolling has the effect of 
removing the entire logical line that starts at the top of the screen 
and then moving all subsequent lines upward to fill in the void. The 
cursor will also move upward if the logical line deleted exceeeds one 
physical line. 

All data going to or coming from the text screen is represented in 8 
bit ATASCII code as shown in Appendix E. 



Text Modes 1 and 2 



In text modes 1 and 2 the screen is physically comprised of either 24 
lines of 20 characters (model) or 12 lines of 20 char acters (mode 2). 
The left and right margins are of no con- sequence in these modes and 
there is no visible cursor. There are no logical lines associated 
with the data and in all regards these modes are treated as graphics 
modes by the handler. 

Data going to or coming from the screen is in the form shown below: 

7 0 
C D 



Where: C is the color/data set select field 



C 

Value 



Color 
(default) 



Color 

Register 

(see 

append i x 



Charac ter 
Set 

CHBAS=*EO 



Charac ter 
S 

CHBAS=*E2 



1 

2 

3 
4 
5 
6 
7 



green 

gold 

gold 

green 

red 

blue 

blue 

red 



P(PFI ) 

(PFO) 

(PFO) 

(PF1 ) 

(PF3) 

(PF2) 

(PF2) 

(PF3) 



/ / 
/ / 



D is a 5 bit truncated ATASKII code which selects the specific 
character within the set selected by the C field. See Appendix 
E for the graphics representations of the characters. 

Database variable CHBAS C02F4D allows for the selection of either 
of two data sets. The default value of $E0 provides the capital 
letters/ numbers and pubnctuation characters; the alternate value 
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of $E2 provides lower case letters and the special character graph- 
ics set. 



GRAPHICS MODES (modes 3 through 11) 

The screen has varying physical characteristics for each of the 
graphics modes as shown in Appendix H. Depending upon the mode, a 1 to 
16 color selection is available for each pixel and the screen size 
varies from 20 by 12 (lowest resolution) to 320 by 192 (highest 
resolution) pixels. 

There is no visible cursor for the graphics mode output. 

Data going to or coming from the graphics screen is represented as 1 
to 8 bit codes as shown in Appendix H and in the GET/PUT diagrams 
f ol lowing. 

SPLIT SCREEN CONFIGURATIONS 

In split screen configurations, the bottom of the screen is reserved 
for four lines of mode 0 text. The text region is controlled by the 
Screen Editor, and the graphics region is controlled by the Display 
handler. Two cursors are maintained in this configuration so that the 
screen segments may be managed independently. 

In order to operate in split screen mode, the Screen Editor must first 
be OPENed and then the Display handler must be OPENed using a separate 
IOCB (with the split screen option bit set in AUX1). 



CIO function descriptions 

The device specific characteristics of the standard CIO functions 
(described earlier in this section) are detailed below: 

OPEN 

The device name is 'S'# and the handler ignores any device number and 
filename specification, if included. 

The handler supports the following options: 

7 O 
AUX1 ! iCISIWIR! ! 

H ¥■ — r- — »- — + — h — I h K 

Where: C = 1 indicates to inhibit screen clear on OPEN. 

S = 1 indicates to setup a split screen configuration (for 

modes 1 through 8 only). 
R & W are the direction bits (read & write). 
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7 0 
AUX2 5 ! mode ! 

Where: mode is the screen mode (0 through 11). 

Note: If the screen mode selected is 0/ then the AUX1 options are 
i gnor ed . 

Because the Display handler dynamically allocates high address memory 
for use in generating the screen display* and because different 
amounts of memory are needed for the different screen modes, the 
Display handler and the user must share memory utilization 
information. Prior to initiating an OPEN command the variable APPMHI 
COOOED should contain the highest address of RAM needed by the user; 
the Screen handler will OPEN the screen only if no RAM is needed at or 
below that address. 

Upon return from a screen OPEN, the variable MEMTOP C02E53 will 
| contain the address of the last free byte at the end of RAM memory 

prior to the screen required memory. 

As a result of every OPEN command, the following screen variables are 
altered: 

The text cursor is enabled (CRSINH = 0). 

The tabs are set to the default settings (2 & 39). 

The color registers are set to the default values, 
(shown in Appendix H). Tabs are set at positions 7,15,23,31,39, 
47, 55, 63, 71, 79, 87, 95, 103, 111, 119. 



CLOSE 

No special handler actions. 
GET CHARACTERS and GET RECORD 

Returns data in the following screen mode dependent forms, where each 
byte contains the data for one cursor position (pixel); there is no 
facility for having the handler return packed graphics data, 
lspace 1; need 20 

7 0 
+-+-+-+-+-+-+-+-+ 

\ ATASCII ! Mode 0 

+ — + — h — h~ + — h — 'r — 

+ -H — -4 h — I I — -\ I h 

! C * D ! Modes 1,2 — C = color, ata set 

select. 

+-+-+-+~+-+-4.-+-4 D = truncated ATASCII. 
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H — -f- — I 1 1 1 1 1 1- 

! zero ! D ! 

H h-H — H — 4- — i I — + ~ + 



Modes 3/5/7 — D = color 



I zero !Di 



Modes 4/6/8 — D ■ color. 



+-+-+-+ — \-- + — i — + ~ + 

{ zero \ D ! 
+-+-+-+-+-4— +-+_- §. 



Modes 9/ 10/ 11 — D = data 



As each data byte is returned/ the cursor is moved to the next cursor 
position. For mode 0/ the cursor will stay within the specified 
margins; for all other modes/ the margins are ignored. 

PUT CHARACTERS and PUT RECORD 

The handler accepts display data in the following screen mode 
dependent forms; there is no facility for the handler to receive 
graphics data in packed form. 



7 0 

+ 4— + - + - + - + - + -- 1— + 

! ATASCII \ 

-i 1 1 1 1 1 ! ! 



Mod e 0 



+ — h-+ — h — 

! C ! D 



H I • I I i I I I- 

i i r\ i 

i » U i 

+ - + — •+■ — H — h— +■ — I h — h 



* Modes 1/2 — C = color, 
D ■ truncated ATASCII. 



Modes 3/5/7 — D = color 



h — +-+ — h — i — i — i — i — h 

! ? ID! 

+ _ + _ + _ + _ + _4._ + _. f _ + 



Modes 4/6/8 — D = color 



— h — H 1 h — I 1 1 h 

i i u i 

+-+-+-+-+-+-+-+-+ 



Modes 9/10,11 — D = data 



NOTE: For all modes/ if the output data byte equals $9B <EOL) that 

byte will be treated as an EOL character; and if the output data 
byte equals *7D (CLEAR) that byte will be treated as a screen 
clear character. 



As each data byte is written/ the cursor is moved to the next cursor 
position. For mode 0/ the cursor will stay within the specified 
margins; for all other modes, the margins are ignored. 

While outputting/ the Display handler monitors the keyboard to detect 
the pressing of the CCTRLU-l key combination; when this occurs, the 
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handler loops internally until that key combination is pressed again, 
thus effecting a stop/start function to freeze the screen display. 
Note that there is no ATASC I I code associated with either the CCTRLD-l 
key combination or the start/stop function; the stop/start function 
may be controlled only from the keyboard (or by altering database 
variable CH as discussed in Appendix K) 



GET STATUS 

No handler action except to set the status to $01. 
DRAW 

This special command draws a simulated "straight" line from the 
current cursor position to the location specified in ROWCRS C0054U and 
COLCRS C0055D. The color of the line is taken from the last character 
processed by the Display handler or Screen Editor. To force the color; 
store the desired value in ATACHR C02FB3. At the completion of the 
command/ the cursor will be at the location specified by ROWCRS and 
COLCRS. 

The value for the command byte for DRAW is *11. 
FILL 

This special command fills an area of the screen defined by two lines 
with a specified color. The command is setup the same as in DRAW/ but 
as each point of the line is drawn/ the routine scans to the right 
performing the procedure shown below (in Pascal notation): 

WHILE PIXEL CROW/ COLD = 0 DO 
BEGIN 

PIXEL CROW; COLD := FILDAT; 
COL : = COL + li 

IF COL > Screen right edge THEN COL 0 
END/ 



An example of a FILL operation is shown below 



+ 1 



4 + 



+ P 



Where: 



' represents the fill operation. 
' ' are the line points/ with '+ ' for the endpoints 



1 — set cursor and plot point 

2 — set cursor and DRAW line. 



56 



REPRODUCTION PROHIBITED WITHOUT PUBLICATIONS DEPT. APPROVAL 

OPERATING SYSTEM, C016555 

3 — set cursor and plot point. 

4 — set fill data value, set cursor and FILL. 

FILDAT C02FD3 contains the fill data and ROWCRS and COLCRS contain the 
cursor coordinates of the line endpoint. The value in ATACHR C02FB3 
will be used to draw the line; ATACHR always contains the last data 
read or written, so if the steps above are followed exactly, ATACHR 
will not have to be modified. 

The value for the command byte for FILL is $12. 



User alterable database variables 

Certain functions of the Display handler require the user to examine 
and/or alter variables in the OS database; the paragraphs that follow 
describe some of the more commonly used handler variables. There are 
additional descriptions to be found in Appendix K Bl-55. 

CURSOR POSITION 

The cursor position for the graphics screen or mode 0 text screen is 
maintained in two variables: ROWCRS [00543, the display row number, 
and COLCRS C00553, the display column number. Both numbers range from 
0 to the maximum number of rows/columns - 1. The cursor may be set 
outside of the defined text margins with no ill effect; this region 
may be read from and written to when the cursor is controlled by the 
user. The home position (0,0) for both text and graphics is the upper 
left corner of the screen. 

ROWCRS is a single byte, and COLCRS is two bytes with the least 
significant byte being at the lower address. 

When these variables are altered by the user, the screen 
representation of the cursor will not move until the next I/O 
operation involving the display is performed. 

INHIBIT/ENABLE VISIBLE CURSOR DISPLAY 

The user may inhibit the display of the text cursor on the screen by 
setting the variable CRSINH C02F03 to any non-zero value. Subsequent 
I/O will not generate a visible cursor. 

The user may enable the display of the text cursor by setting CRSINH 
to zero. Subsequent I/O will then generate a visible cursor. 

TEXT MARGINS 

As mentioned earlier, the text screen has user alterable left and 
r.ight margins, which are normally set to 2 and 39 by the OS The 
variable LMARGN C00523 defines the left margin and RMARGN COO 53 3 
defines the right margin. The leftmost margin value is O and the 
rightmost margin value is 39. . 
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The margin values inclusively define the useable portion of the screen 
for all operations in which the user does not explicitly alter the 
cursor location variables as described prior to this paragraph. 



COLOR CONTROL 



As part of normal stage 2VBLANK processing (as discussed in Section 6) 
the hardware color registers are updated using data from the OS 
database. Shown below are the database variable names, the hardware 
register names and the function of each register; see Appendix H for 
the mode dependent uses for the registers. 



Database 



Hardware 



Func t i on 



COLORO 
COLOR 1 
C0L0R2 
COLORS 
C0L0R4 



COLPFO 
COLPF1 
C0LPF2 
C0LPF3 
COLBK 



PFO - 
PF1 - 
PF2 - 
PF3 - 
BAK - 



Playf ield 
Playf ield 
Playf ield 
Playf ield 
Playf ield 



0. 
1. 

2. 
3. 

background 



PCOLRO 
PC0LR1 
PC0LR2 
PC0LR3 



COLPMO 
C0LPM1 
C0LPM2 
C0LPM3 



PMO - 
PM1 - 
PM2 - 
PM3 - 



- P 1 ay er /mi s s i 1 e 0 

- P lay er /mi ss i 1 e 1 

- Player/missile 2 

- Player/missile 3 



Theory of operation 



The Display handler automatically sets up all memory resources 
required to create and maintain the screen display at OPEN time. 
The screen generation hardware requires that two distinct data areas 
exist for graphics modes: 1) a display list and 2) a screen data 
region; a third data area must exist for text modes which defines the 
screen representation for each of the text characters. The ATARI 
personal computer HARDWARE MANUAL must be referenced for a com- 
plete understanding of the material that is to follow. 

The simplified block diagram below shows the relationships between 
the memory and hardware registers used to setup a screen display 
(without player/missile objects) by the 0. S. ; be aware that the 
hardware allows for many other possibilities. 



xx xxx DATABASE HARDWARE 

xx xxx VARIABLE REGISTER 

(Updated every 
VBLANK ) 

MEMTOP 



Display SDL DLISTL 

List 

SDL DLISTH 
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Screen Data 



SAVMSC 



Graph i c s 
and /or 
text 



end of RAM memory 



Char. 
Def s. 



EOOO CHBAS=EO 



CHBASE 



in OS 



E3FF 



ROM 



Specials and 
numbers 

Cap i ta 1 

Let t er s 



EOOO 



EiOO 



Color 
Color i 
Color 2 
Color 3 
Color 4 



Color COLPFO 
regs. C0LPF2 
C0LPF3 
COLBK 



Special 
Grap h i c s 



Lower 

case 

Letters 



E200 



E300 



In the preceding diagram the following relationships are present: 

Database variables SDL/STL/SDL/STH containthe address of the 
current display list* as part of the Stage 1 VBlank process this 
address isstored in the hardware display list address r 
DLISTL and DLISTH. 



;The display list itself defines the characteristics of the 
screen to be displayed and points to the memory containing the 
data to be displayed. 

Database variable CHE AS contains the msb ofthe base address of 
the character representations for the character data (text modes 
only). The default value for this variable is $EOi which declares that 
the character representations start at memory address EOOO (the charac 
set provided by the 0. S. in ROM). Each character is defined as an 
8X8 bit matrix., requiring 8 bytes per character; since a character 
code contains up to 7 significant bits (set of 128 characters), 1024 
bytes are required to define the largest set. The O. S. ROM con- 
tains the default set in the region from EOOO to E3FF. 

All Character codes are converted by the handler from ATASC 1 1 
to an internal code and vice versa, as shown below: 



ATASC 1 1 
CODE 



INTERNAL 
CODE 



00- IF 
20-3F 



40-5F 
00- IF 
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40-5F 
60-7F 
8Q-9F 
AO-BF 
CO-DF 
EO-FF 



20-3F 
60-7F 
CO-DF 
S0-9F 
AO-BF 
EO-FF 



The character set in ROM is layed out in internal code order. 
The reason for the internal code being different from the external 
code (ATASCII) is based upon three considerations: 1) ATASCII 
codes for all but the special graphics characters were to be sim- 
ilar to ASCII, specifically the a 1 p hab e t i c , numer i c , and punctuation 
character codes are identical to ASCII, 2) in text modes 1 and 2 it wa 
was desired that one haracter subset included capital letters, 
numbers and punctiuation and the other character subset include 
lower case letters and special graphics characters and 3) the codes 
for the capital and lower case letters were to be identical 
in text modes 1 and 2. 

Database variables COLORO through C0L0R4 contain the current color 
register assignments; these are also stored in the hardware color 
registers aspart of the stage 1 VBLANK process, thus providing 
synchronized color changes. Appendix H provides more information 
regarding the color registers. 

Database variable SAVMSC points to the lowest memory address of 
the screen data region, which corresponds to the data displayed 
at the upper left corner of the display. 

When the display handler receives an OPEN command, it first de- 
termines the screen mode from the OPEN IOCB. It then allocates mem- 
ory from the end of RAM (as specified by database variable RAMTOP) 
downward; first for the screen data and then for the display list. 
If thereis sufficient memor yava i lab 1 e, the screen data region is 
cleared, the display list is created/ and the display list address 
is stored to the database. 



Screen Ed i tor (E: ) 

The Screen Editor is a read/write handler that uses the Keyboard 
handler and the Display handler to provide "line at a time' 1 
input with interactive editing functions, as well as formatted 
output. 

The Screen Editor supports the following CIO functions: 



OPEN 
CLOSE 

GET CHARACTERS 
GET RECORD 
PUT CHARACTERS 
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PUT RECORD 

GET STATUS (null function) 

The Screen Editor may produce the following error statuses: 

see Keyboard handler and Display handler. 

The Screen Editor is one of the resident handlers, and therefore has a 
set of device vectors starting at location E400. 

The Screen Editor may be thought of as a program which reads key data 
from the Keyboard handler and sends each character to the Display 
handler for immediate display; and in addition, accepts data from the 
user to send to the Display handler. In addition, the Screen Editor 
reads data from the Display handler (not the Keyboard handler) for the 
user. In fact, the Keyboard handler, Display handler and the Screen 
Editor are all contained in one monolithic hunk of code, and thus, are 
even more closely related than indicated. 

Most of the behaviors already defined for the Keyboard handler and the 
Display handler apply to the Screen Editor, so the discussions in this 
section will pertain to deviations from those behaviors or to 
additional features that are part of the Screen Editor only. The 
Screen editor deals only with text data (screen mode 0) as described 
in section 5. A split screen configuration is allowed which is also 
explained. 

Whereas the Display handler allows the graphics and text screens to be 
readable on program demand, the Screen Editor gives the operator at 
the keyboard the control of what portion of the screen is to be read 
and when it is to be read. The choice of when is governed by the 
CRETURN3 key, and the choice of where is governed by the location of 
the cursor when the CRETURN3 key is pressed. When the CRETURN3 key is 
pressed, the entire logical line within which the cursor resides is 
then made available to the calling program. Trailing blanks in a 
logical line are never returned as data, however. After all of the 
data in the line has been sent to the caller (this may entail multiple 
READ CHARACTERS functions if desired), the cursor is positioned to the 
beginning of the logical line following the one just read. 

CIO function descriptions 

The device specific characteristics of the standard CIO functions 
(described earlier in section 5) are detailed below: 

OPEN 

The device name is 'E', and the Screen Editor ignores any device 
number and filename specification, if included. 

The Screen Editor supports the following option: 
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7 0 
— 

AUX1 ! iWiRi IF! 

Where: R & W are the direction bits (read and write). 

F = 1 indicates that a "forced read" is desired (see GET 
CHARACTER and GET RECORD for more information). 

CLOSE 

No special handler actions. 
GET CHARACTER and GET RECORD 

Normally the Screen Editor will return data to the caller only when 
prompted to do so by having the operator at the keyboard press the 
CRETURND key. However/ the "forced read" OPEN option/ allows a caller 
to read text data without operator intervention; when a read operation 
is commanded/ the Screen Editor will return data from the start of the 
logical line in which the text cursor is located and then move the 
cursor to the beginning of the following logical line. A read of the 
last logical line on the screen will cause the screen data to scroll. 

A special case occurs when characters are output without a terminating 
EOL and then additional characters are appended to that logical line 
from the keyboard. When the CRETURN3 key is pressed/ only the keyboard 
entered characters are sent to the caller/ unless the cursor has been 
moved out of and then back into the logical line/ in which case all of 
the logical line will be sent. 

PUT CHARACTER and PUT RECORD 

The handler accepts ATASC 1 1 characters as one character per byte. 
Sixteen of the 256 ATASCII characters are control codes; the EOL code 
has universal meaning/ but most of the other control codes have 
special meaning only to a display or print device. The Screen Editor 
processing of the ATASCII control codes is explained below: 

CLEAR ($7D) — The current display is cleared of all data and the 
cursor is placed at the home position (upper left corner of the 
screen ) . 

CURSOR UP ($1C) — The cursor is moved up by one physical line. The 
cursor will wrap from the top line of the display to the bottom line. 

CURSOR DOWN ($1D) — The cursor is moved down by one physical line. 
The cursor will wrap from the bottom line of the display to the top 
line. 

CURSOR LEFT ($1E) — The cursor is moved left by one column. The 
cursor will wrap from the left margin of a line to the right margin of 
the same line. 
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CURSOR RIGHT (*1F) — The cursor is moved right by one column. The 
cursor will wrap from the right margin of a line to the left margin of 
the same line. 



BACKSPACE ($7E> — The cursor is moved left by one column (but never 
past the beginning of a logicical line) and the character at that new 
position is changed to a blank ($20). 

SET TAB <$9F> — A tab point is established at the logical line 
position at which the cursor is residing. The logical line tab 
position is not synonymous with the physical line column position 
since the logical line may be up to 3 physical lines in length. For 
example/ tabs may be set at the 15th/ 30th/ 45th/ 60th and 75th 
character positions of a logical line as shown below: 



0 2 
— L 

xx- 
X x~ 
xx- 



9 19 



29 



39 Screen column # 
— R L/R = margins. 



T T 



T _ 



A logical line, 
x = inaccesible 
columns. 



Note the effect of the left margin in defining the limits of the 
logical line. 

The handler default tab settings are shown below: 



0 2 
— L- 



9 



19 



29 



39 Screen column # 
R L/R = margins. 



x xT 

x x 

X x 



T T T T T 



A logical line, 
x - inaccesible 
col umns. 



CLEAR TAB ($9E> — The current cursor position within the logical line 
is cleared from being a tab point. There is no "clear all tab points 1 ' 
facility provided by the handler. 

TAB <$7F> — The cursor is moved to the next tab point in the current 
logical line/ or to the beginning of the next line if no tab point is 
found. Note that this function will not increase the logical line 
length to accommodate a tab point outside the current length (e.g. the 
logical line length is 3S characters and there is a tab point at 
position 50). 



INSERT LINE (*9D> — The physical line in which the cursor resides/ 
and all physical lines below that line/ are moved down by one physical 
line; the last logical line on the display may be truncated as a 
result. The blank physical line at the insert point becomes the 
beginning of a new logical line. A logical line may be split into two 
logical lines by this process/ the last half of the original logical 
line begin concatenated with the blank physical line formed at the 
insert point. 
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DELETE LINE <*9C> — The logical line in which the cursor resides is 
deleted and all data' below that line is moved upward to fill the void. 
Empty logical lines are created at the bottom of the display. 

INSERT CHARACTER ($FF) — The character at the cursor position, and 
all remaining characters in the logical line, are moved one position 
to the right and the character at the cursor position is set to blank. 
The last character of the logical line will be lost when the logical 
line is full and a character is inserted. The number of physical lines 
comprising a logical line may increase as a result of this function. 

DELETE CHARACTER <$FE) — The character on which the cursor resides is 
removed, and the remainder of the logical line to the right of the 
deleted character is moved to the left by one position. The number of 
physical lines comprising a logical line may decrease as a result of 
this function. 

ESCAPE <*1B> — The next non-EOL character following this code is 
displayed as data, even if it would normally be treated as a control 
code. The sequence ESC ESC will cause the second ESC character to be 
displayed. 

BELL <$FD) — An audible tone is generated; the display is not 
modified. 

END OF LINE <$9B> — In addition to its record termination function, 
the EOL causes the cursor to advance to the beginning of the next 
logical line. When the cursor reaches the bottom line of the screen, 
the receipt of an EOL will cause the screen data to scroll upward by 
one logical line. 

Output start/stop using the CCTRL3-1 key is processed. as explained in 
section 5:Display handler (S:). 



GET STATUS 

The handler takes no action other than to set the status to $01. 



User alterable database variables 

See also the Display handler database variable discussion. 
CURSOR POSITION (split screen) 

When in a split screen configuration, ROWCRS and COLCRS are associated 
with the graphics portion of the display and two other variables, 
TXTROW C0290D and TXTCOL C02911, are associated with the text window. 
TXTROW is a single byte, and TXTCOL is two bytes with the least 
significant byte being at the lower address. Note that the most 
significant byte of TXTCOL should always be zero. 
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The home position (O/O) for the text window is the upper left corner 
of the window. 

ENABLE/INHIBIT OF CONTROL CODES IN TEXT 

Normally all text mode control codes are operated upon as received/ 
but sometimes it is desireable to have the control codes displayed as 
if they were data characters. This is done by setting the variable 
DSPFLG C02FED to any non-zero value before outputting the data 
containing control codes. Setting DSPFLG to zero restores normal 
processing of text control codes. 

Cassette handler (C: ) 

The Cassette device is a read or write device with a handler 
that supports the following CIO functions: 

OPEN 
CLOSE 

GET CHARACTERS 
GET RECORD 
PUT CHARACTERS 
PUT RECORD 

GET STATUS (null function) 

The Cassette handler may produce the following error statuses: 

*80 — CBREAK3 key abort. 

*84 — Invalid AUX1 byte on OPEN. 

*88 — End-of-file. 

*8A-90 — SIO error set (see Appendix C). 

The Cassette handler is one of the resident handlers, and therefore 
has a set of device vectors starting at location E440. 



CIO function descriptions 

The device specific characteristics of the standard CIO functions are 
detailed below: 

OPEN 

The device name is 'C'* and the handler ignores any device number and 
filename specification, if included. 

The handler supports the following option: 

7 O 

AUX2 IC! ! 
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Where: C = 1 indicates that the cassette is to be read/written without 

stop/start between records (continuous mode). 

When the cassette is OPENed for input/ a single audible tone is 
generated/ using the keyboard speaker, as a prompt for the operator to 
verify that the cassette player is setup for reading (power on, Serial 
Bus cable connected/ tape cued to start of file and PLAY button 
depressed). When the cassette is ready/ the operator may press any 
keyboard key (except [BREAK] ) to initiate tape reading. 

When the cassette is OPENed for output/ two closely spaced audible 
tones are generated/ using the keyboard speaker/ as a prompt for the 
operator to verify that the cassette player is setup for writing (as 
above/ plus REC button depressed). When the cassette is ready/ the 
operator may press any keyboard key (except CBREAKD) to initiate tape 
writing. Note that there is no way for the computer to verify that the 
REC button (or even the PLAY button) is depressed/ so it is possible 
for the file not to be written/ with no immediate indication of this 
fact. 

There is a potential problem with the cassette in that when the 
cassette is OPENed for writing/ the motor keeps running until the 
first record (128 data bytes) is written. If 128 data bytes are 
written or the cassette is CLOSEd within about 30 seconds of the OPEN, 
and no other serial bus I/O is performed, then there is no problem. 
However/ if those conditions are not met/ some noise will be written 
to the tape prior to the first record and an error will occur when 
that tape file is read later. If lengthy delays are anticipated 
between the time the cassette file is OPENed and the time that the 
first cassette record (128 data bytes) is written, then a dummy record 
should be written as part of the file; typically 128 bytes of some 
innocuous data would be written/ such as all zeroes, all $FFs or all 
blanks ($20). 

The system will sometimes emit whistling noises after cassette I/O has 
occurred. The sound can be eliminated by storing $03 to SKCTL CD20F], 
thus bring POKEY out of the two-tone (FSK) mode. 

CLOSE 

The CLOSE of a tape read stops the cassette motor. 

The CLOSE of a tape write does the following: 

Writes any remaining user data in the buffer to tape. 
Writes an End-of-file record. 
Stops the cassette motor. 

GET CHARACTERS and GET RECORD 

The handler returns data in the following format: 
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7 0 
+-+-+-+~+-+~+-+~+ 

I data byte ! 

• 1 1 1 K — • 1 H 



PUT CHARACTERS and PUT RECORD 

The handler accepts data in the following format: 

7 O 
+--+-+-+-+-+-+_+_+ 

S data byte I 



The handler attaches no significance to the data bytes written, a 
value of $9B (EOL) causes no special action. 

GET STATUS 

The handler does no more than set the status to $01. 
Theory of operation. 

The cassette handler writes and reads all data in fixed length records 
of the format shown below: 



+ — i — +— + — i- — h — i- — »-—•+■ 

i 01010101! 
+-+-+-+-+-+--+-+-.+ 

10 10 10 10 1! 

+ — h- + - + - + - + - + — h~ + 

* control byte ! 
+-+-+-+-+-+-+-+-.+. 



Speed measurement bytes. 



= data = 

! bytes ! 

+-+-+-+--+-+-+-+-+ 

! checksum j 
+-+-+- +-+-4— +-+-+ 



(Managed by SIQ, not the 
hand 1 er ) . 



The control byte contains one of three values: 

*FC indicates the record is a full data record (128 bytes). 

*FA indicates the record is a partially full data record; fewer 
than 128 bytes were supplied by the user. This case may occur only 
in the record prior to the End~of-f i 1 e. The number of user 
supplied data bytes in the record is contained in the byte prior 
to the checksum. 

« 

*FE indicates the record is an End-of file record; the data 
portion is all zeroes for an End-of-file record. 
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The checksum is generated and checked by the SIO routine and is part 
of the tape record* but is not contained in the handler's record 
buffer CASBUF C03FD3. 

The processing of the speed measurement bytes during cassette reading 
is discussed in section 4:Central database description. 



File structure 

The Cassette handler writes a file to the cassette device with a file 
structure that is totally imposed by the handler (soft format). A file 
consists of the following three elements: 

A 20 second leader of mark tone. 
Any number of data record frames. 
End-of file frame. 

The cassette frames referred to above are formatted as shown below: 

frame = pre-record write tone (PRWT)* 

+ data record* 
+ post-record gap (PRC) 

The non-data portions of a frame have characteristics which are 
dependent upon the write OPEN mode* i.e. continuous or start/stop. 

Stop/start PRWT = 3 seconds of mark tone. 
Continuous PRWT = .25 seconds of mark tone. 

Stop/start PRG = up to 1 second of unknown tones. 

Continuous PRG ■ from O to n seconds of unkonwn tones* where n is 
dependent upon user program timing. 

The inter-record gap (IRG) between any two records will thus consist 
of the PRG of the first record followed by the PRWT of the second 
record. 



Printer handler <P: ) 

The Printer device is a write only device with a handler that supports 
the following CIO functions: 

OPEN 
CLOSE 

PUT CHARACTERS 
PUT RECORD 
GET STATUS 

The Printer handler may produce the following error statuses: 
8A-90 — SIO error set (see Appendix C). 
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The Printer handler is one of the resident handlers, and therefore has 
a set of device vectors starting at location E430. 

CIO function descriptions 

The device specific characteristics of the standard CIO functions are 
detailed below: 

OPEN 

The device name is 'P', and the handler ignores any device number and 
filename specification, if included. 

CLOSE 

The handler writes any data remaining in its buffer to the printer 
device, with trailing blanks to fill out the line. 

PUT CHARACTERS and PUT RECORD 

The handler accepts print data in the following format: 

7 0 

+ — h- + — H — H — — | »- — + 

! ATASCII ! 

+ - + — + - + — I — H h — h — + 

The only ATASCII control code of any significance to the handler is 
the EOL character. The printer device ignores bit-7 of every data byte 
and prints a sub-set of the remaining 128 codes, see Appendix 0 for 
the printer character set. 

The handler supports the following print option: 

7 O 

+ - + |- + h h h — + 

AUX2 I print mode ! 

Where: $4E ('N'> selects normal printing (40 chars per line). 

$53 ('S') selects sideways printing (29 chars per line). 
$57 ('W') selects wide printing (not supported by printer 
device. ) . 

Any other value (including 00) is treated as a normal (N) print- 
select, without producing an error status. 

GET STATUS 

The handler obtains a four byte status from the printer 
controller and puts it in system location DVSTAT C02EA1. The 
format of the status bytes is shown below: 
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+ — »- — + - + h — H h — h- + 

i command stat. ! DVSTAT + 0 

-i i » 1 h — + ~ + — h 

! AUX^ of prev. I + 1 

-f — ! — + - + \ I — + - + 

! timeout I + 2 

+ - + - + -+ — i » r- — + 

! (unused) ! + 3 

The command status contains the following status bits: 

Bit-0 indicates an invalid command frame was received. 
Bit-1 indicates an invalid data frame was received. 
Bit-7 indicates an intelligent controller (normally = 0). 

The next byte contains the AUX2 value from the previous operation. 

The timeout byte contains a controller provided maximum timeout value 
<in seconds). 



Theory of operation. 

The ATARI 82ofcrinter is a line at a time printer/ rather than a 
character at a time printer, so the user data must be buffered by the 
handler and sent to the device in records corresponding to one print 
line (40 characters for normal/ 29 characters for sideways). 



The printer device does not attach 
character/ so the handler does the 
sees an EOL. 



any significance to the EOL 
appropriate blank fill whenever it 



Disk File Manager CD': ) 

The File Management Subsystem (FMS ) includes a disk bootable (RAM 
resident) DFM which maintains a collection of named 
files on diskettes. Up to 4 disk drives (Dl: through D4 : ) may be 
accessed/ and up to 64 files per diskette may be accessed; the system 
disks supplied by ATARI allow a single disk drive (Dl) and up to 3 
OPEN files, but these numbers may be altered by the user as described 
later in this section. The Disk File Manager supports the following 
CIO functions: 
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OPEN FILE 
OPEN DIRECTORY 
CLOSE 

GET CHARACTERS 
GET RECORD 
PUT CHARACTERS 
PUT RECORD 
GET STATUS 

NOTE 

POINT 

LOCK 

UNLOCK 

DELETE 

RENAME 

FORMAT 

The Disk File Manager may produce the following error statuses: 

$03 — Last data from file (EOF on next read). 
*88 — End-of-file. 

*8A-90 — SIO error set (see Appendix C). 
*A0 — Drive number specification error. 

*A1 — No sector buffer available (too many open files) 
*A2 — Disk full. 

*A3 — Fatal I/O error in directory or bitmap. 

*A4 — Internal file # mismatch (structural problem). 

*A5 — File name specification error. 

$A6 — Point information in error. 

*A7 — File locked to this operation. 

*A8 — Special command invalid. 

*A9 — Directory full (64 files). 

*AA — File not found. 

*AB — Point invalid (file not OPENed for update). 
CIO function descriptions 

The device specific characteristics of the standard CIO functions are 
detailed below: 

OPEN FILE 

The device name is 'D' and up to 4 disk drives may be accessed (Dl 
through D4); the disk filename may be from 1 to 8 characters in 
length with an optional 1 to 3 character extension. 

The OPEN FILE command supports the following options: 

7 0 
+-+-+-+-+-+-+-+-+ 

AUX1 i SW.'R! !AI 

-I j 1 j 1 j , , ^ 
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Where: W & R are the direction bits. 
WR = 00 is invalid 

01 indicates OPEN for read only. 

10 indicates OPEN for write only. 

11 indicates OPEN for read/write (update). 

A = 1 indicates appended output when W = 1. 

v 

The various valid AUX1 options are now explained. 
OPEN input (AUX1 - *04> 

The indicated file is OPENed for input. Any wild card characters are 
used to search for the first match. If the file is not found, an error 
status is returned, and no file will be OPENed. 

OPEN output (AUX1 = *08> 

The indicated file is OPENed for output starting with the first byte 
of the file, if the file is not locked. Any wild card characters are 
used to search for the first match. If the file already exists, the 
existing file will be DELETED before OPENing the named file as a new 
file. If the file does not already exist, it will be created. 

A file OPENed for output will not appear in the directory until it has 
been CLOSEd. If an output file is not properly CLOSEd, some or all of 
the sectors that were acquired for it may be lost until the disk is 

reformatted. 

A file that is OPENed for output may not be OPENed concurrently 
for any other access. 

OPEN append (AUX1 = *09) 

The indicated file is OPENed for output starting with the byte after 
the last byte of the existing file (which must already exist), if the 
file is not locked. Any wild card characters are used to search for 
the first match. 

If a file OPENed for append is not properly CLOSEd, the appended data 
will be lost, the existing file will remain unmodified and some or all 
of the sectors that were acquired for the appended portion may be lost 
until the disk is reformatted. 

OPEN update CAUXl m *GC ) 

The indicated file (which must already exist) will be OPENed for 
update provided it is not locked. Any wild card characters are used to 
search for the first match. 

The GET, PUT, NOTE and POINT operations are all valid, and may be 
intermixed as desired. 
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If a file OPENed for update is not properly CLOSEd, a sector's worth 
of information may be lost to the file. A file OPENed for update may 
not be extended. 



Device/filename spec if i cation 

The handler expects to find a device/filename specification of the 
following form: 

DC<numb er>3 : <f i 1 ename><EOL> 
where: 

<number> ::= IS 2 13} 4 

<filename> ::= C<pr imar y>]| C . C<e x t ens i on> 3 3<t ermi na t or> 

<primary> : : = an upper case alpha character followed by 0 to 7 

alphanumeric characters. If the primary name is less 
than 8 characters, it will be padded with blanks; if 
it is greater than 8 characters, the extra 
characters will be ignored. 

<extension> :: = Zero to 3 alphanumeric characters. If the 

extension name is missing or less than 3 characters, 
it will be padded with blanks; if it is greater than 
3 characters, the extra characters will be ignored. 

<termi^ator> ::= CEOLXbIank> 

The following are all valid device/filenames for the disk: 

Di : GAME. SRC 
D: MANUAL6 
D: . WHY 
D3: FILE. 
D4: BRIDGE. 002 



Filename wildcarding 

The filename specification may be further generalized to include the 
use of the "wildcard" characters and '?'. These wildcard 

characters allow portions of the primary and/or extension to be 
abbreviated as follows: 

The '?' character in the specification allows any file name character 
at that position to produce a "match". For example, WH? will match 
files named WHO, WHY, WH4, etc., but not a file named WHAT. 

The character causes the remainder of the primary or extension 

field in which it is used to be effectively padded with '?' 
characters. For example, WH* will match WHO, WHEN, WHATEVER, etc. 

Some valid uses of wildcard specifications are shown below: 
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«*. SRC Files having an extension of SRC. 

BASIC* Files named BASIC with any extension. 

*. * Al 1 f i les. 

H*. ? Files beginning with H and having a 0 or 1 

character extension. 



If wildcarding is used with an OPEN FILE command; the first file found 
(if any) that meets the specification will be the one (and only one) 
opened. 



OPEN DIRECTORY 



The OPEN DIRECTORY command allows the user to read directory 
information for the selected filename(s)/ using normal GET CHARACTERS 
or GET RECORD commands. The information read will be formatted as 
ATASC 1 1 records, suitable for printing, as shown below. Wildcarding 
may be used to obtain information for multiple files or the entire 
disk. 



The OPEN DIRECTORY command uses the same CIO parameters as a standard 
OPEN FILE command: 

COMMAND BYTE - $03 

BUFFER ADDRESS = pointer to device/filename specification. 



AUX1 - $06 



After the directory is OPENed, a record will be returned to the caller 
for each file that matches the OPEN specification. The record, which 
contains only ATASCII characters, is formatted as shown below: 

1 

123456789012345678 

+ — k- — I — H — ■+- — h — h — + — I- — »- — •*- — h — + — t- — h- + — h 

! s ! b ! primary name • ext ! b ! count ! e I 
+-+-+-+ -+-+-+- 



Where: s = or ' with indicating file locked, 

b = blank. 

primary name = left justified name with blank fill, 
ext = left justified extension with blank fill, 
b = blank. 

count = number of sectors comprising the file, 
e = EOL (*9B). 

After the last filename match record is returned, an additional record 
is returned, which indicates the number of unused sectors available on 
the disk. The format for this record is shown below: 
/space 1; need 5 

1 

12345678901234567 

+ — + — »- — + — + — h — I — + — h — h — i I h — -+- — + — h — h — i- 
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icounti FREE SECTOR S!e! 

+ + - + - + - + - + + + - + - + - + - + + „ + „ + 

Where: count m the number of unused sectors on the disk 
e = EOL <*9B>. 

The EOF statuses ($03 and *88 ) are returned as per a normal data file 
when the last directory record is read. 

The OPENing of another disk file while the directory read is OPEN will 
cause subsequent directory reads to malfunction, so care must be taken 
to avoid this situation. 

CLOSE 

On closing a file read, the handler releases all internal resources 
being used to support that file. 

On closing a file write, the handler writes any residual data from its 
file buffer for that file to the disk, updates the directory and 
allocation map for the associated disk, and releases all internal 
resources being utilized to support that file. 

GET CHARACTERS and GET RECORD 

Characters are read from the disk and passed to CIO as a raw data 
stream; none of the ATASC 1 1 control characters have any special 
significance. A status of *03 is returned when the last byte of 
file is returned and a status of $88 is returned if an attempt is 
made to read past the last byte. 



PUT CHARACTERS and^ PUT RECORD 

Characters are obtained from CIO and written to the disk as a raw data 
stream; none of the ATASC 1 1 control characters have any special 
significance. 

GET STATUS 

The indicated file is checked and one of the following status byte 
values is returned in ICSTA and register Y: 

*01 — File found & unlocked. 
*A7 — File locked. 
*AA — File not found. 



Special CIO functions 

The DFM supports a number of SPECIAL commands, which are device 
specific; these are explained in the paragraphs that follow. 



NOTE (COMMAND BYTE = $25) 
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This command returns to the caller the exact disk location of the next 
byte to be read or written, in the variables shown below: 

ICAX3 = l.s. b. of the disk sector number. 
ICAX4 « m. s. b. of the disk sector number. 
ICAX5 = relative sector displacement to byte (0-124). 

POINT (COMMAND BYTE = *26 ) 

This command allows the user to specify the exact disk location of the 
next byte to be read or written. In order to use this commmand, the 
file must have been OPENed with the "update" option. 

ICAX3 = l.s.b. of the disk sector number. 
ICAX4 * m. s. b. of the disk sector number. 
ICAX5 = relative sector displacement to byte (0-124). 

LOCK 

This command allows the user to prevent write access to any number of 
named files. Locked files may not be deleted, renamed nor opened for 
output unless they are first unlocked. Locking a file that is already 
locked is a valid operation. The handler expects a device/filename 
specification; then all occurrences of the filename specified will be 
locked, using the wildcard rules. 

The following IOCB paramters are setup by the user prior to calling 

CIO: 

COMMAND BYTE = *23 

BUFFER ADDRESS ■ pointer to device/filename specification. 

After a LOCK operation, the following IOCB parameter will have been 
altered: 

STATUS = result of LOCK operation; see Appendix B for a list of 
possible status codes. 

UNLOCK 

This command allows the user to remove the lock status of any number 
of named files. Unlocking a file that is not locked is a valid 
operation. The handler expects a device/filename specification; then 
all occurrences of the filename specified will be unlocked* using the 
wildcardrules. 

The following IOCB paramters are setup by the user prior to calling 

CIO: 

COMMAND EYTE = *24 

3UFFER ADDRESS = pointer to device/filename specification. 
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After an UNLOCK operation/ the following IOCB parameter will have been 
al tered : 

STATUS ■ result of UNLOCK operation; see Appendix B for a list of 
possible status codes. 

DELETE 

This command allows the user to delete any number of unlocked named 
files from the directory of the selected disk and to deallocate the 
disk space used by the files involved. The handler expects a 
device/filename specification; then all occurences of the filename 
specified will be deleted/ using the wildcard rules. 

The following IOCB paramters are setup by the user prior to calling 

CIO: 

COMMAND BYTE = *2l 

BUFFER ADDRESS = pointer to d e vi c e / f i 1 ename specification. 

After a DELETE operation/ the following IOCB parameter will have been 
altered: 

STATUS = result of DELETE operation; see Appendix B for a list of 
possible status codes. 

RENAME 

This command allows the user to change the filenames of any number of 
unlocked files on a single disk. The handler expects to find a 
device/filename specification as shown below: 

<device spec>: <f i 1 ename spec>, <f i 1 ename spec><EOL> 

All occurrences of the first filename will be replaced with the second 
filename/ using the wildcard rules. No protection is provided against 
forming duplicate names/ and once formed/ duplicate names cannot be 
separately renamed or deleted; however, an OPEN FILE command will 
always select the first file found that matches the filename 
specification/ so that file will always be accessible. The RENAME 
command does not alter the content of the files involved/ merely the 
name in the directory. 

Examples of some valid RENAME name specifications are shown below: 

Dl : #. SRC/ # TXT 
D: TEMP/ FDATA 
D2: F*, F*. OLD 

The followinq IOCB paramters are setup by the user prior to calling 

CIO. 

COMMAND BYTE ■ $20 
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BUFFER ADDRESS = pointer to device/filename specification. 

After a RENAME operation/ the following IOCS parameter will have been 
altered: 

STATUS ■ result of RENAME operation; see Appendix B for a list of 
possible status codes. 

FORMAT 



This command allows the user to physically format a diskette, which is 
required before the diskette can be used to store data; the physical 
formatting process writes a new copy of every sector on the "soft 
sectored" diskette, with the data portion of each sector containing 
all zeroes. When the physical formatting process is complete/ the FMS 
creates an initial Vol ume Table of Contents (VTOC) and an initial File 
Directory; as part of this process the boot sector (#1) is permanently 
reserved. The result of the FORMAT process will be the creation of an 
"empty" non-system disk. 

The following IOCB paramters are setup by the user prior to calling 
CIO: 



COMMAND BYTE 



BUFFER ADDRESS = pointer to device specification. 

After a FORMAT operation/ the following IOCB parameter will have been 
altered: 



STATUS = result of FORMAT operation; see Appendix B for a list of 
possible status codes. 



To create a system disk/ a 
to sectors #2-n. This is ac 
'DOS. SYSS which is a name 
it is not in the directory 



copy of the boot file must next be written 

complished by writing the file named 

that is recognized by the FMS even though 
initially. 



Theory of operation 

The resident OS initiates the disk boot process, as described in 
section 10.2/ by reading disk sector #1 to memory and then 
transferring control to the "boot continuation address" (boot address 
+ 6). The boot continuation program contained in sector #1 then 
continues to load the remainder of the File Management Subsystem to 
memory using additional information contained in sector #1. The File 
Management Subsystem loaded will contain a Disk File Manager and., 
optionally/ a Disk Utilites (DOS) package. 

When the boot process is complete/ the Disk File Manager will allocate 
additional RAM for the creation of sector buffers. Sector buffers are 
allocated based upon information in the boot record as shown below: 
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Byte 9 ■ maximum number of OPEN files; one buffer per (the maximum 

value is 8). 

Byte 10 = drive select bits; one buffer per (1-4 only). 

The Disk File Manager will then insert the name 'D' and the 
handler vector table address in the Device Table. 



NOTE: 



There is a discrepancy between the Disk File Manager's numbering 
of disk sectors (0-719) and the disk controller's numbering of 
disk sectors (1-720); as a result, only sectors 1- 719 are used 
by the Disk File Manager. 



The Disk File Manager 
and writes; the DFM's 
direc tory/f i le/b i tmap 



uses the Disk handler to perform all disk reads 
function is to support and maintain the 
structures as described in the following pages: 



FMS DISK UTILIZATION 



The map below shows the disk sector utilization for a standard 720 
sector diskette. 



BOOT record 

FMS BOOT 
file 
'DOS. SYS ' 



•+ 
! 

•+ 
i 



User 
File 
Area 



i 
i 

I 



VOTC(note 2) 

File 
Directory 



I 



User 
File 
Area 



! 

+ 

t 
i 



i 
i 



unused I 



Sector 1 
Sector 2 -+ 
Sector n 
Sector n+1 - 



+- Note 1 
! 

+ 



Sector 359 (*167) 
Sector 360 <*168) 
Sector 361 (*169) 



Sector 368 (*170) 



Sector 719 <*2CF) 
Sector 720 (*2D0) 



NOTE 1 - If the diskette is not a system diskette, then the User File 

Area starts at sector 2 and no space is reserved for the FMS 
BOOT file. 



Note 2 — VOTC stands for volume table of contents. 
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FMS BOOT RECORD FORMAT 



The FMS BOOT record (sector #1) is a special case 
software as described in section 10.2. The format 
record is shown below: 



of disk booted 
for the FMS BOOT 



+ + 

boot flag = O 



# sectors « 1 



boot address 
= 0700 



ini t address 



JMP 



*4B 



boot read 
c on t inua t i on 
address 



max files » 3 
drive bits = 1 
alloc d ire = 0 
boot image end 
address + 1 



boot flag O 0 



sector count 



'DOS. SYS' 
starting 
sector number 



code for 2nd 
phase of boot 



Byte 0 
1 
2 



9 Note 1 



10 Note 2 



11 Note 3 



FMS 

configuration 
data 



14 Note 4 



15 Note 5 



NOTE 1 - Byte 9 specifies the maximum number of concurrently OPEN 

files to be supported. This value may range from 1 to 8. 
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NOTE 2 - Byte 10 specifies the specific disk drive numbers to be 

supported using a bit encoding scheme as shown below: 

7654321 0 
+-+ — i — + — t- — i — i — h — (- 



!4!3!2!1! where a 1 indicates a selected drive 

+ — I 1 1 1 1 ( 1 y. 



NOTE 3 - Byte 11 specifies the buffer allocation direction, this byte 

should equal 0. y 

NOTE 4 - Byte 14 must be non-zero for the second phase of the boot 

process to initiate; this flag indicates that the file 
DOS. SYS" has been written to the disk. 

NOTE 5 - This byte is assigned as being the sector count for the 

DOS. SYS ' file, but is in actuality an unused byte. 

BOOT PROCESS MEMORY MAP 

The diagram below shows how the boot sector (part of file DOS SYS) and 
subsequent sectors are loaded to memory as part of the boot process. 

+ + Memory address 0700 

{ data from boot ! ; 
= sector read by = j 
i resident OS J 077C 



; data from rest ! 



! of 'DOS. SYS ' J • 

i read by the \ | 

r program in the = ; 

{ boot sector. ! j 

• : 



077D 



end of boot 



VOLUME TABLE OF CONTENTS ( VTOC ) 



The format for the FMS volume table of contents (VTOC, sector^360) is 
shown in the diagram below: 

* + 

\ directory type I p Byte 0 Note 1 

! maximum (lo) \ \ i Note 2 

* sector # h- I 

! - 02C5 (hi) 1 % I 
+ + I 

I number of (lo) ! 5 3 Note 3 

+ sectors + 
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available (hi) 



volume bit map = 



5ft 



10 



) oh 



A 



■ 



C//U 



I 

+ 



I 

■+ 



Where the volume bit map is organized as shown below: 



7 0 
+_+_+-+-+-+-+-+-+ 

! 1 2 3 4 5 6 7! £/\ 
+_+-+-+-+-+-+-+-+ 

8 9 i 



0 



8 



\ 



6 



\ 



Byte 10 of VTOC 



+_+-+-+-+-+-+-+-+ 



ii 



99 



1 



At each map bit position, a 0 indicates the corresponding sector is in 
use and a 1 indicates that the sector is available. 



NOTE 1 - The directory type byte must equal 0. 
NOTE 2 - 



The maximum sector number is apparently not used because it 
is incorrectly set to 709 decimal although the true maximum 
sector number is 719, for the DFM. 



NOTE 3 - The number of sectors available is initially set to 709 after 

a diskette is freshly formatted; this number is adjusted as 
files are created and deleted to show the number of sectors 
available. The sectors which are initially reserved are 1 
and 360-368. 

FILE DIRECTORY FORMAT 

There are eight sectors (361-368) reserved for a file directory, each 
sector containing directory information for up to eight files, thus 
providing for a maximum of 64 files for any volume. The format of a 
single 16 byte file entry is shown below: 
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APPROVAL 



. mm mmm — 




flag byte 

sector (lo) ! 

count + 

jj£ g(l i -fay (hi) I 
+ 

starting (lo) ! 
♦ sector + 
number (hi) ! 

( 1 ) I 
+ 

(2) ! 

(3) : 



+ 

1 

+ 
+ 

! 



file 
name 
pr imar y 



(4) 
(5) 
(6) 
(7) 



1 
« 

-5- 

1 
1 



Byte 0 
1 



I 
I 

+ 

! 

+ 

1 
1 



file 
name 
extension 



(8) 
(1) 
(2) 
(3) 




X § 



Where the 




The 



*00 
*40 
*41 
*60 
*80 



lag byte has the following bits assigned: 

the file has been d e 1 e t e d -— 
the file is in use.— — ^ ] ( | 
the file is locked. 
OPEN output. 



byte may take on the following values: 

entry not yet used (no file). 

entry in use (normal CLOSEd file). 

entry in use (OPEN output file). 

entry in use (locked file). 

entry available (prior file deleted). 




rr \ * 

r 



Sector count is the number of sectors comprising the file 
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FMS FILE SECTOR FORMAT 



The format of a sector in a user's data file is shown below: 



7 0 



+-+-+-+-+-+-+-+-+ 



data 



+0 



+ - + — j- — | | H- + — | — + 



file ft !hi 



+ 125 



+-+--}--+-+ — h-+ + 
{forward pointer! 

H 1- — ¥■ — I — + — + — h 

J S \ byte count ! 



+ 127 



+ 126 




The file # is a redundant piece of information which is used to verify 
file integrity; the file number field contains the value of the 
directory position of that file. If there is ever a mismatch between 
the file's position in the directory and the file number as contained 
in each sector, the Disk File Manager will generate the error *A4. 

The forward pointer field contains the ten bit value of the disk 
sector number of the next sector of the file. The pointer will equal 
zero for the last sector of a file. 

The S bit indicates whether or not the sector is a "short sector" (one 
containing fewer than 125 data bytes). S is equal to one when the 
sector is short. 

The byte count field contains the number of data bytes in the sector. 



Mori CIO I/O 

Some portions of the I/O subsystem may or must be accessed 
independently of the Central I/O Utility (CIO); this section discusses 
those areas. 



Resident device handler vectors 

All of the OS ROM resident device handlers may be accessed via sets of 
vectors which are part of the OS ROM. The primary reason for using 
these vectors would be to increase the speed of I/O operations which 
utilize fixed device assignments, such as output to the Display 
handler. For each resident handler there is a set of vectors ordered 
as shown below: 
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APPROVAL 



- OPEN 


— + 
— h 
— + 




- CLOSE 


— h 


fiTi i 


- OFT BYTF 


1- 

• 




— PUT BYTF 


+ 

— + 

• 




- GET STATUS 


4- 

+ 


+8 


SPECIAL 




+ 10 


JMP 
INIT 


— + 
- + 


+ 12 



See section 9 for a detailed description of the data interface for 
each of these handler entry points. 

Each of the vectors contains the address <lo,hi> of the handler entry 
point minus one, so a technique similar to the one shown below is 
required to access the desired routines: 



VTBASE=*E400 



; BASE OF VECTOR TABLE. 



LDX 
LDA 
JSR 

LDX 
JSR 
STA 



#x x 

data 

GOVEC 

#yy 

GOVEC 

data 



; OFFSET TO DESIRED ROUTINE. 

; SEND DATA TO ROUTINE. 

; OFFSET TO DIFFERENT ROUTINE 

; GET DATA FROM ROUTINE. 



GOVEC TAY 
LDA 
PHA 
LDA 
PHA 
TYA 
RTS 



VTBASE+1, X 
VTBASE, X 



; SAVE REGISTER A. 

; ADDRESS M. S. B. TO STACK. 

; ADDRESS L. S. B. TO STACK. 

; RESTORE REGISTER A. 

; JUMP TO ROUTINE. 



The JMP INIT slot in each set of vectors jumps to the handler 
initialization entry (not minus one). 

The base address of the vector set for each of the resident handlers 
is shown below: 



Screen Editor (E: ) 
Display handler (S: ) 
Keyboard handler <K: ) 



E400 
E410 
E420 
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Printer handler (P: > E430. 
Cassette handler (C: ) E440. 



The resident disk handler is not CIO compatible, so its 
interface does not use a vector set; the disk handler interface 
is discussed in section 5. 

Resident Disk handler — US£ S PO£> D^ouj £ ZOOO dun«y fVs ro^i,^ 

The resident Disk handler (not to be confused with the Disk File or ^eH«i^ 
Manager) is responsible for all physical accesses to the disk. The 
unit of data transfer for this handler is a single disk sector 
containing 128 data bytes. 

Communication between the user and the Disk handler is effected using 
the system's Device Control Block (DCB ) / which is also used for 
handler/SIO communication as described in section 9. The DCB is twelve 
bytes long/ in which some bytes are user alterable and some are for 
use by the Disk handler and/or the Serial I/O Utility (SIO). The user 
supplies the required DCB parameters and then does a JSR DSKINV 
CE4533. 



Each of the DCB bytes will now be described/ and the system equate 
file name for each will be given. 

SERIAL BUS I.D. — DDEVIC C03003 

This byte is setup by the Disk handler to contain the Serial Bus I.D. 
for the drive to be accessed/ and is not user alterable. 

DEVICE NUMBER — DUNIT C0301D 

This byte is setup by the user and contains the disk drive number to 
be accessed (1 - 4) 



COMMAND BYTE — DCOMND C 0302 3 

This byte contains the disk device command to be performed and is 
setup by the user. 

STATUS BYTE — DSTATS C 0303 3 



This byte contains the status of the command upon 
caller. See Appendix C for a list of the possible 

BUFFER ADDRESS — DBUFLO 1 0304 1 b DBUFHI C 0305 1 

This two byte pointer contains the address of the source or 
destination of the disk sector data. For the disk status command; the 
user need not supply an address; the Disk handler will obtain the 
status and insert the address of the status buffer in this field. 

DISK TIMEOUT VALUE ~~ DTIMLO L 0306 1 



return to the 



status codes. 
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This timeout value (in whole seconds) is supplied by the handler for 
use by SIO. 

BYTE COUNT — DBYTLO C03083 & DBYTHI [03093 

This two byte counter indicates the number of bytes transferred to or 
from the disk as a result of the most recent command/ and is setup by 
the handler. 

SECTOR NUMBER — DAUX1 C030A'D & DAUX2 C030BII 



This two byte number specifies the disk 
read or write. DAUX1 contains the least 
contains the most significant byte. 



sector number (0 
significant byte/ 



• 719) to 
and DAUX2 



Disk handler commands 

There are five commands supported by the Disk handler 
GET SECTOR 

(PUT SECTOR — *** not supported by handler *** ) 
PUT SECTOR WITH VERIFY 
STATUS REQUEST 
FORMAT DISK 



GET SECTOR (Command byte = *52) 



The handler reads the specified sector to the user's buffer and 
returns the operation status. The following DCB parameters are set by 
the user prior to calling the Disk handler: 

COMMAND BYTE = *52. 



DEVICE NUMBER = disk drive number (1-4). 

BUFFER ADDRESS = pointer to user's 128 byte buffer 

SECTOR NUMBER ■ sector number to read. 



Upon return# several of the other DCB parameters will have been 
altered/ however, the STATUS BYTE will be the only one of interest to 
the user. 




PUT SECTOR (Command byte = *50) 
*** Not supported by current handler *** 

The handler writes the specified sector from the user's buffer 
returns the operation status. The following DCB parameters are 
the user prior to calling the Disk handler: 

■ 

COMMAND BYTE - *50. 



and 

set by 
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DEVICE NUMBER = disk drive number (1-4). 

BUFFER ADDRESS = pointer to user's 128 byte buffer. 

SECTOR NUMBER = sector number to write. 

Upon return/ several of the other DCB parameters will have been 
altered/ however/ the STATUS BYTE will be the only one of interest to 
the user. 



PUT SECTOR WITH VERIFY (Command byte = $57) 



The handler writes the specified sector from the user's buffer and 
returns the operation status. This command differs from PUT SECTOR in 
that the disk controller reads the sector data after writing to verify 
the write operation, (byte by byte compare???) Aside from the COMMAND 
BYTE value/ the calling sequence is identical to PUT SECTOR. 

STATUS REQUEST (Command byte - $53) 

The handler obtains a four byte status from the disk controller and 
puts it in system location DVSTAT C02EA3. The operation status format 
is shown below: 



7 0 
+-+-+-+-+-+-+~+-+ 

! command stat. ! 

+ — H — h — i — » — — h — H- + 

I hardware stat. ! 



+-+-+-+-+-+.-+-+-+ 
! timeout i 

-I • 1 1 1 1 1- h- + 

! ( unused ) ! 
+-+-+-+-+-+-+ — h-+ 



DVSTAT + 0 



+ 1 



+ 2 



+ 3 



r 



The command status contains the following status bits 



Bit-0 
Bit-1 
Bi t-2 
Bit-3 
Bit-4 



indicates 
indicates 
indicates 
indicates 
indicates 



an invalid command frame was received 
an invalid data frame was received, 
that a PUT operation was unsuccessful 
that the disk is write protected, 
active/standby. 



The hardware status byte contains the status register of the INS1771-1 
Floppy Disk Controller chip used in the disk controller. See the 
documentation for that chip for information relating to the meaning of 
each bit in the byte. 

The timeout byte contains a controller provided maximum timeout value 
(in seconds) to be used by the handler. 

The following DCB parameters are set by the user prior to calling the 
Disk handler: 
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COMMAND BYTE ■ $53. 

DEVICE NUMBER - disk drive number (1-4). 

Upon return, several of the other DCB parameters will have been 
altered, however, the STATUS BYTE mill be the only one of interest to 
the user. 



FORMAT DISK (Command byte = $21) 

The handler commands the disk controller to format the entire disk and 
then to verify it. All bad sector numbers/ up to a maximum of 63/ are 
returned and put in the supplied buffer/ followed by two bytes of all 
ones ($FFFF). The following DCB parameters are set by the user prior 
to calling the Disk handler: 

COMMAND BYTE = $21. 

DEVICE NUMBER = disk drive number (1-4). 

BUFFER ADDRESS = pointer to user's 128 byte buffer. 

Upon return/ the following DCB parameters will be of interest to the 
user: 

STATUS BYTE = status of operation. 

BYTE COUNT = number of bytes of bad sector information in 
user's buffer/ not including the $FFFF terminator. If there 
are no bad sectors/ the count will equal zero. 

Educational System Program Cassettes 

Educational System Program Cassette tapes are recorded in 1/4 track 
stereo format at 1 7/8 inches per second. The tape can be recorded in 
both directions., where tracks i and 2 are side A left and right; and 
tracks 3 and 4 are side B right and left (industry standard). Dn each 
side/ the left channel (1 or 4/ outside tracks) is used for audio and 
the right channel (2 or 3, inside tracks) is used for digital 
inf or mat ion. 

The audio channel is recorded in the normal manner. The digital 
channel is recorded using FSK encoding and the recording is 
asynchronous byte., with no record structure/ 



All data bits on the tape (not including start/stop) are stored in bit 
inverted form; that is, all zero bits are stored as one bits and vice 

v e r s a . 

ATARI EDUCATIONAL SYSTEM CHARACTER SET 
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HEX CHAR NOTES 

00 Null Reserved for Atari use — see text. 

01 SOH Dorsett screen hold charactei see text. 

02 STX Inhibit marked text. 

03 ETX Clear Screen 

04 EOT Stop Tape 

05 ENQ Enable marked text 

06 ACK 

07 BEL End of tape 

08 BS Select left response 

09 HT Select middle response 
oA LF Select right response 
OB VT Select any response 

OC FF Reserved for Dorsett 

OD CR Carriage return 

OE SO Reserved for Dorsett 

OF SI Reserved for Dorsett 

10 DLE 

11 DC1 Border Brown (note: colors may not match 

this description. 

12 DC2 Border red 

13 DC3 Border Orange 

14 DC4 Border Yellow 

15 NAK Border Green 

16 SYN Border Blue 

17 ETB 

18 CAN 

19 EM Text background brown 
1A SUB Text Background red 

IB ESC Text background orange 

1C FS Text background yellow 

ID OS Text background green 

IE RS Text background blue 

IF US 

20 Space 

21 ! 
22 

23 Pi 

24 * 

25 % 

26 Overline 

27 ' 

28 ( 

29 ) 

2A Wheel 

2B + 

2C 

2D 

2E 

2F / 

30 Centered period 

31 1 

32 2 
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33 

WW 


3 

w 


34 

w~ 


4 


35 


5 


36 


6 

w 


37 


7 


38 


8 


39 


9 


3A 


• 
• 


3B 


• 
i 


3C 


<- 


3D 

W JLr 


SB 


3E 


> 


3F 

wl 


• 




40 


41 


A 


42 


B 


43 


c 


44 


D 

mam 


45 


E 


46 


F 


47 


w 


4R 
•to 


u 

n 


49 


T 
1 


4A 


,1 

w 


4B 


Lt 
r\ 


4C 


I 


4D 


M 


4E 


N 


4F 


n 


50 


p 


51 


Q 


52 


R 

i \ 


53 

WW 


s 

w 


54 


T 
i 


55 


u 

w 


56 


v 


57 


w 


58 


X 


59 


Y 
• 


5A 


7 


5B 






\ 






JC 


sk 


SF 




AO 




w X 




62 


b 


A3 

w w 


*•* 

la 


64 


d 


65 


e 


66 


f 


67 


g 


68 


h 



"Head" 
"Torso" 

(actually somewhat lowered) 
Double parallel vertical slashes 
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69 
6 A 
6B 
6C 
6D 
6E 
6F 
70 

72 

74 
75 
76 
77 
78 
79 

9 7A 

713 

7C 

7C 

7D 

7F 



99 
9A 
9B 
9C 
9D 
9E 



l 

J 
k 

1 

m 

n 

o 

P 

q. 

r 

s 
t 
u 

V 

w 

X 

y 



"Re-entrant" (dotted) slash 
"Re-entrant" (dotted) backslash 
Right- justified vertical slash 
n-tilde (for Spanish) 
three parallel horizontal lines 

NOTE: All characters above are the same character 
but 'flagged' (see text) if the top bit 
is set/ except that the flag bit is ignored 
on all control characters except the fol- 
lowing (flag is not allowed on NULL): 



EM 


Inset 


Brown 


SUB 


Inset 


Red 


ESC 


Inset 


Orang e 


FS 


Inset 


Yellow 


GS 


Inset 


Green 


RS 


Inset 


Blue 



Serial bus I/O (SIO) 



Input/Output to devices other 
ATARI controller port devices 



than the keyboard/ the screen and the 
must utilize the Serial I/O bus. This 
bus contains data/ control and clock lines to be used to allow the 
computer to communicate with external devices on this "daisy chained 1 ' 
bus. Every device on the bus has a unique identifier and will respond 
only when directly addressed. 

The resident system provides a Serial I/O Utility (SIO)/ which 
provides a standardized high-level program interface to the bus. SIO 
is utilized by the resident Disk/ Printer and Cassette handlers and i 
intended to be used by non-resident handlers (as described in section 
9) or by applications/ as well. For a detailed description of the 
program/SIO interface and for a detailed bus specification refer to 
section 9. 

Device characteristics 

This section describes the physical characteristics of the devices 
that interface to the ATARI 400 and ATARI 800 Personal Computer 
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Systems. Where applicable* data capacity, data transfer rate* storage 
format.. SIO interface and cabling mill be detailed. 



Keyboard 

The keyboard input rate is limited by the OS keyboard reading 
procedure to be 60 characters per second. The code for each key is 
shown in Table 77$ section 5. A picture of the ATARI 400 Personal 
Computer System keyboard is shown on the following page. The keyboard 
hardware has no buffering and is rate limited by the debounce 
algorithm used. 



Display 

The television screen display generator has many capabilities that are 
not used by the Display handler (as described in section 5 and shown 
in Appendix H), there are additional display modes, object generators/ 
hardware display scrolling and many other features which are described 
in the ATARI Personal Computer System HARDWARE MANUAL. 

Since all display data is stored in RAM; the display data update rate 
is limited primarily by the software routines that generate and format 
the data and access the RAM. The generation of the display from the 
RAM is accomplished by the ANTIC and CTIA chips using Direct Memory 
Access (DMA) to access the RAM data. 

The internal storage formats for display data for the various modes 
are detailed in the ATARI Personal Computer System HARDWARE MANUAL. 



ATARI 410 Program Recorder 

Recorder has the following characteristics: 



C-60 tape (unformatted). 

C-60 tape (formatted/ continuous). 

C-60 tape (formatted., stop/start). 



second (unformatted). 

second, average (formatted; stop/start). 



1/4 track stereo format at 1 7/8 inches per 
second. The tape can be recorded in both directions, where tracks 1 
and 2 are side A left and right; and tracks 3 and 4 are side B right 
and left (industry standard). On each side; the left channel (1 or 4) 



The ATARI 410 Program 
DATA CAPACITY: 

x x characters per 
xx characters per 
xx characters per 

DATA TRANSFER RATES: 

xx characters per 
xx characters per 

STORAGE FORMAT: 

Tapes are recorded in 
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is used for audio and the right channel (2 and 3) is used for digital 
information. 

The audio channel is recorded the normal way. The digital channel is 
recorded using the POKEY two-tone mode producing FSK data at up to 600 
baud. The MARK frequency is 5327 Hz and the SPACE frequency is 3995 
Hz. The transmission of data is asynchronous byte serial as seen from 
the computer; POKEY reads or writes a bit serial FSK sequence for each 
byte/ in the following order: 

1 start bit (SPACE) 
data bit-0 -+ 
data bit-1 ! 

+- O = SPACE, 1 ■ MARK, 
data bit-6 ! 
data bit-7 -+ 
1 stop bit (MARK*) 

The only control the computer has over tape motion is motor 
start/stop; and this only if the PLAY button is pressed by the user. 
In order for recording to take place/ the user must press both the REC 
and PLAY buttons on the cassette. The computer has no way to sense the 
position of these buttons/ nor even if a 410 is cabled to the 
computer/ so the user must be careful when using this device. 
SIO INTERFACE 

The cassette device utilizes portions of the serial bus 
hardware/ but does not follow any of the protocol as defined in 
section 9. 



ATARI 820 Printer 

The ATARI 820 printer has the following characteristics: 
DATA CAPACITY: 

40 characters per line (normal printing) 
29 characters per line (sideways printing) 

DATA TRANSFER RATES: 

Bus rate: xx characters per second. 

Print time (burst): xx characters per second. 

Print time (average), xx characters per second. 

STORAGE FORMAT: 

3 7/8 inch wide paper. 

5X7 dot matrix/ impact printing. 

Normal format — 

40 characters per line. 
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6 lines per inch (vertical). 

12 characters per inch (horizontal). 

Sideways format — 

29 characters per line. 

6 lines per inch (vertical). 

9 characters per inch (horizontal). 

SIO INTERFACE 

The controller serial bus I.D. is $40. 

The controller supports the following SIO commands (see section 5 for 
more information regarding the handler and section 9 for a general 
discussion of bus commands): 

GET STATUS 

The computer sends a command frame of the format shown below: 

Devi c e I.D. = $40. 
Command byte * $53. 
Auxilliary I = doesn't matter. 
Auxilliary 2 « doesn't matter. 
Checksum = checksum of bytes above. 

The printer controller responds with a data frame of the format shown 
in earlier in this section as part of the GET STATUS discussion. 

PRINT LINE 

The computer sends a command frame of the format shown below: 

Devi c e I.D = $40. 
Command byte = $57. 
Auxilliary 1 - doesn't matter. 

Auxilliary 2 - $4E for normal print or $53 for sideways. 
Checksum = checksum of bytes above. 

The computer sends a data frame of the format shown below: 

Leftmost character of line (column 1). 
Next character of line (column 2). 

Rightmost character of line (column 40 or 29). 
Checksum byte. 

Note that the data frame size is variable, either 41 or 30 bytes in 
length., depending upon the print mode specified in the command frame. 
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ATARI 810 Disk Drive 

The ATARI BICPfcisk has the following characteristics: 
DATA CAPACITY: 

720 sectors of 126 bytes each (Disk handler format). 

70? sectors of 125 data bytes each (Disk File Manager format). 

DATA TRANSFER RATES: 

Bus rate: xx characters per second. 
Seek time: xx msec, per track + xx msec. 
Rotational latency: xx msec maximum (xx rpm). 

STORAGE FORMAT: 

5 1/4 inch diskette; soft sectored by the controller. 
40 tracks per diskette. 
ie sectors per track. 
128 bytes per sector. 

Controlled by National INS1771-1 formatter/controller chip 
Sector interlace factor = 

SIO INTERFACE 

The controller serial bus I.D. s range from $31 (for 'Di ' ) to $34 
(for 'D4'). 

The controller supports the following SIO commands (see earlier in 
this section for information about the disk handler and section 9 
a general discussion of bus commands): 

GET STATUS 

The computer sends a command frame of the format shown below: 

Device I D. = $31-34. 
Command byte = $53. 
Auxilliary 1 = doesn't matter. 
Auxilliary 2 = doesn't matter. 
Checksum = checksum of bytes above. 

The disk controller responds with a data frame of the format shown 
earlier in this section as part of the STATUS REQUEST discussion. 

PUT SECTOR (WITH VERIFY) 

The computer sends a command frame of the format shown below: 

Device I.D. ■ $31-34 
Cdmmand byte = $57. 

Auxilliary 1 = low byte of sector number. 
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Auxilliary 2 = high byte of sector number (1-720). 
Checksum = checksum of bytes above. 

The computer sends a data frame of the format shown below: 

128 data bytes. 
Checksum byte. 

The disk controller writes the frame data to the specified sector; 
then reads the sector and compares the content with the frame data. 
The COMPLETE byte value indicates the status of the operation. 

PUT SECTOR (NO VERIFY) 

The computer sends a command frame of the format shown below: 

Device I. D. = $31-34 
Command byte = $50. 

Auxilliary 1 = low byte of sector number. 
Auxilliary 2 ■ high byte of sector number (1-720). 
Checksum = checksum of bytes above. 

The computer sends a data frame of the format shown below: 

128 data bytes. 
Checksum byte. 

The disk controller writes the frame data to the specified sector, 
then sends a COMPLETE byte value which indicates the status of the 
op era t ion. 

GET SECTOR 

The computer sends a command frame of the format shown below: 

Device I. D. = $31-34 
Command byte = $52. 

Auxilliary 1 = low byte of sector number. 
Auxilliary 2 = high byte of sector number (1-720). 
Checksum = checksum of bytes above. 

The disk controller sends a data frame of the format shown below. 

128 data bytes. ■ 
Checksum byte. 

FORMAT DISK 

The computer sends a command frame of the format shown below: 

Device I. D. = $31-34 
Command byte = $21. 
Auxilliary 1 - doesn't matter. 
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Auxilliary 2 
Checksum 



doesn ' t matter, 
checksum of bytes above. 



The disk controller completely formats the disk (generates 40 tracks 
of 18 soft sectors per track with the data portion of each sector 
equal to all zeroes) and then reads each sector to verify its 
integrity. A data frame of 128 bytes plus checksum is returned in 
which the sector numbers of all bad sectors (up to a maximum of 63 
sectors) are contained/ followed by two consecutive bytes of $FF. If 
there are no bad sectors on the disk the first two bytes of the data 
frame will contain $FF. 



ATARI 85Q rM tnterface Module 



See ATARI 850 Interface Module Manual. 
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6 - 



INTERUPT PROCESSING. 



Introduction 

There are three general interrupt types processed by the 6502 
microcomputer: c^Jj>_ r ? se ^' non-maskable interrupts (NMI) and m 
interrupts (IRQ). The IRQ type may be enabled and disabled usi 
6502 CLI and SEI instructions/ whereas the NMI type may not be 
disabled at the processor level; the NMI interrupts other than 
CS/RESET3 key may be disabled at the ANTIC chip/ however. 

The system events that can cause interrupts are listed below: 
Chip reset - Power up 



NMI - Display list interrupt (unused by OS) — 1 n T 
Vertical blank (50/60 Hz) 0 
CS/RESET3 key 

IRQ - Serial bus output ready 

Serial bus output complete 
Serial bus input ready 

Serial bus proceed line (unused by system) 
Serial bus interrupt line (unused by system) 
POKEY timers 1/ 2 & 4 
Keyboard key 
CBREAK3 key 

6502 BRK instruction (unused by OS) 

The chip reset interrupt is vectored via location FFFC to E477 where a 
JMP vector to the power up routine is located. All NMI interrupts are 
vectored via location FFFA to the NMI interrupt service routine at 
> E7B4 and all IRQ interrupts are vectored via location FFFE to the IRQ 
interrupt service routine at E6F3/ at which point the cause of the 
interrupt must be determined by a series of tests. For some of the 
events there are built-in monitor actions, and for other events the 
corresponding interrupts are disabled or ignored. The system provides 
RAM vectors so that the user may intercept interrupts when necessary 

The remainder of section 6 will describe system actions for the 
various interrupt causing events/ define the many RAM vectors and 
provide recommended procedures for dealing with interrupts. 



Chip reset 



Chip reset is generated in response to a power up condition. The 
system is completely initialized as described in section 7. 

Non-maskable interrupts (NMI) 
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When an NMI interrupt occurs/ control is transferred through the ROM 
vector directly to the system NMI interrupt service routine; where a 
cause for the interrupt is determined by examining hardware register 
NMIST CD40F3. If a display list interrupt is pending/ a jump is made 
through the global RAM vector VDSLST C02003; the OS does not use 
display list interrupts so VDSLST is initialized to point to an RTI 
instruction and must be changed by the user before a display interrupt 
is allowed to be generated. 

If the interrupt is not a display list interrupt/ then a test is made 
to see if it is a CS RESETD key interrupt; if so, then a jump is made 
to the CS RESET] initialization routine (see section 7 for details of 
CS RESETD initialization). 

If the interrupt is neither a display list interrupt nor a CS/RESET3 
key interrupt then it is assumed to be a vertical blank (VBLANK) 
interrupt and the following actions occur: 

Registers A/ X & Y are pushed to the stack. 
The interrupt request is cleared (NMIRES CD40F3). 

A jump is made through the "immediate" vertical blank global RAM 
vector VVBLKI C0222D which normally points to the stage 1 VBLANK 
processor. 

Assuming that VVBLKI has not been changed by the user/ the following 
actions occur: 

The stage 1 VBLANK processor is executed (see section 6.3.1). 

Tests are made to see if a critical code section has been 
in terr up ted ; i f so/ all registers are restored and an RTI 
instruction returns from the interrupt to the critical section. A 
critical section is determined by examining the CRITIC flag 
C0042D and the processor I bit; if either are set then the 
interrupted section is assumed to be critical. 

If the interrupt was not from a critical section/ then the stage 
2 VBLANK processor is executed (see section 6.3.2). 

A jump is then made through the "deferred" vertical blank global 
RAM vector VVBLKD C02243 which normally points to the VBLANK exit 
routine. 

Assuming that VVBLKD has not been changed by the user, the following 
actions occur: 

The 6502 A/ X ?y Y registers are restored. 

An RTI instruction is executed. 

> 

Note that there are ROM vectors to the stage 1 VBLANK processor and to 
the VBLANK exit routine available to the user who alters the deferred 
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and immediate VBLANK RAM vectors but still wants to enable normal 
system processes as well or restore the original vectors without 
having to save them. The instruction at E45F is a JMP to the stage 1 
VBLANK processor; the address at CE460/ 2D is the value normally found 
in VVBLKI. The instruction at E462 is a JMP to the VBLANK exit 
routine; the address at CE463/ 23 is the value normally found in 
VVBLKD. 



Note also that a jump is made through vector VVBLKI on every VBLANK 
interrupt; but a jump is made through vector VVBLKD only on interrupts 
from non-critical code sections. 



Stage 1 VBLANK process 



\b/A bUK 25sr 



J 



As part of the stage 1 VBLANK processing which will be performed at 
every VBLANK interrupt are the following: 

The 3 byte frame counter RTCLOK [0012-0014] is incremented; 
RTCLOK+0 is the MSB and RTCLOK+2 is the LSB. This counter wraps 
to zero when it overflows (every 77 hours or so) and continues 
counting. 



The Attract mode variables are processed 
4 B10-12. 



as described in section 



System timer 1 CDTMVi £0218,23 is decremented if it is non-zero; 
if the timer goes from non-zero to zero then an indirect JSR is 
performed via CDTMAi C0226,2j. 



Stage 2 VBLANK process 



As part of the stage 2 VBLANK 
those VBLANK interrupts which 
the following: 



processing which will be performed at 
do not interrupt critical sections are 



The 6 502 processor I bit is cleared, thus enabling the IRQ 
interrupts. 

Various hardware registers are updated with data from the OS 
database as shown below. 

Reason for update 
Display list end. 



Database item 


Hardware reg. 


SDLSTH 


C 0231 3 


DLISTH 


CD403 3 


SDLSTL 


C 0230 3 


DLISTL 


CD4023 


SDMCTL 


lUc,c!F J 


DMACTL 


CD 400 1 


CHBAS 


C02F4 3 


CHBASE 


CD4093 


CHACT 


C02F3] 


CHACTL 


CD401 j 


GPRIOR 


C 0 2 & P j 


PRIOR 


CD01B j 


C0i_QR0 


L0eiC4j 


COLPFO 


CD0163 


COLOR 1 


C02C5] 


C0LPF1 


CD0173 


C0L0R2 


C02C61 


C0LFF2 


[D0183 



At trace mode. 
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C0L0R3 


C02C73 


C0LPF3 


CD0193 


r* fit nn n 

CDLDR4 


L 02C8 J 


COLBK 


CD01 A3 


PCOLRO 


C02C03 


COLPMO 


CD012 3 


PC0LR1 


C02C13 


C0LPM1 


CD0133 


PC0LR2 


C02C23 


C0LPM2 


CD0143 


PC0LR3 


C02C33 


COLPM3 


CD0153 


Constant = 8 


CONSOL 


CD01F3 



Console speaker off 



System timer 2 CDTMV2 C021 A, 23 is decremented if it is non-zero; 
if the timer goes from non-zero to zero then an indirect JSR is 
performed through CDTMA2 C022S, 23. 

System timers 3, 4 & 5 are decremented if non-zero; the 
corresponding flags are set to zero for each timer that changes 
from non-zero to zero. 



Timer Timer value 



3 
4 
5 



CDTMV3 C021C23 
CDTMV4 C021E,23 
CDTMV5 C0220, 23 



Timer flag 

CDTMF3 C022A, 1 3 
CDTMF4 C022C, i 3 
CDTMF5 C022E, 1 3 



A character is read from the POKEY keyboard register and stored 
in CH C02FC3 if auto-repeat is active. 

The keyboard debounce counter is decremented if not equal to zero 
and if no key is pressed. 

Keyboard auto-repeat is processed as described in section 4.5 ES. 

Game controller data is read from the hardware to the RAM 
database as shown below. 



Hardware reg. 

PENV CD40D3 
PENH CD40C3 
PORTA CD3003 



Database item 



PORTB CD3013 



POTO 



CD2003 



LPENV 

LPENH 

STICKO 

STICK1 

PTRIGn 

PTRIGO 

PTRIG1 

PTRIG2 

PTRIG3 

STICKS 

STICK3 

PTRIGn 

PTRIG4 

PTRIG5 

PTRIG6 

PTRIG7 

PADDLO 



C 023 5 3 
C02343 
C02783 
C 0279 3 

C027C3 
C027D3 
C027E3 
C027F3 
C027A3 
L027B3 

C02803 
C02B1 3 
C02B23 
1 0283 3 
C 0270 3 



Func t i on 
Lightpen. 
Joysticks £< 
pot triggers 



Pot controllers 
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P0T7 CD2073 
TRIGO CD0013 
TRIG3 CD0043 



PADDL7 C02773 
STRIGO C02843 
STRIG3 C02B73 



Joystick triggers. 



Maskable interrupts (IRQ) 

When an IRQ interrupt occurs control is transferred through the 
immediate IRQ global RAM vector VIMIRQ CQ2163; ordinarily this vector 
points to the system IRQ handler whose actions are described below. 

A cause for the interrupt is found by examining the IRQST CD20E3 
register and the PIA status registers PACTL CD3023 PBCTL CD3033. For 
the interrupt found/ the interrupt status bit is cleared. One 
interrupt event is cleared and processed for each interrupt service 
entry; if multiple IRQs are pending a separate interrupt will be 
generated for each until all are serviced. 

The rest of this section describes how the system IRQ interrupt 
service routine deals with each of the possible IRQ causing events. 

The 6502 A register is pushed to the stack. 

If the interrupt is due to serial I/O bus output ready/ then 
clear the interrupt and jump through global RAM vector VSEROR 
C020C3. 

If the interrupt is due to serial I/O bus input ready/ then clear 
the interrupt and jump through global RAM vector VSERIN C020A3. 

If the interrupt is due to serial I/O bus output complete; then 
clear the interrupt and jump through global RAM vector VSEROC 



If the interrupt is due to POKEY timer #1/ then clear the 
interrupt and jump through global RAM vector VTIMR1 C02103. 

If the interrupt is due to POKEY timer #2/ then clear the 
interrupt and jump through global RAM vector VTIMR2 C02123. 

If the interrupt is due to POKEY timer #4/ then clear the 
interrupt and fall into the following test due to a bug in the OS 
interrupt processor! 

If the interrupt is due to a keyboard key being pressed (other 
than CBREAK3 i CSTART3 / C0PTI0N3/ CSELECT3 ) / then clear the 
interrupt and jump through global RAM vector VKEYBD [02083. 

If the interrupt is due to the CBREAK3 key being pressed/ then 
clear the interrupt/ set the BREAK flag BRKKEY C00113 to zero, 
and clear the following: start/stop flag SSFLAG C02FF3/ cursor 
inhibit flag CRSINH C02F03 and Attract mode flag ATRACT C004D3. 
Then return from the interrupt after restoring the 6502 A 
register from the stack. 



C020E3. 



103 



REPRODUCTION PROHIBITED WITHOUT PUBLICATIONS DEPT. APPROVAL 
OPERATING SYSTEM* C016555 



If the interrupt is due to the serial I/O bus proceed line, then 
clear the interrupt and jump through global RAM vector VPRCED 
C 02021. 

If the interrupt is due to the serial I/O bus interrupt line, 
then clear the interrupt and jump through global RAM vector 
VINTER C0204D. 

If the interrupt is due to a 6502 BRK instruction, then jump 
through global RAM vector VBREAK [02063. 

If none of the above, restore the 6502 A register and return from 
the interrupt (RTI). 



Interrupt initialization 

Whenever the system is powered up or the CS/RESET3 key is pressed, the 

interrupt subsystem is completely r e- i n i t i a 1 i z ed . The hardware 

registers are all cleared and the interrupt global RAM vectors are set 
to the following configurations: 



Vector 




Value 


Type 


Func t i on 


VDSLST 


C 0200 3 


E7B3 


Nlil 


RTI — ignore interrupt. 


VVBLKI 


[0222 3 


E7D1 


II 


System stage 1 VBLANK. 


CDTMA1 


[0226 3 


EBFO 


II 


SIO timeout timer. 


CDTMA2 


[ 0228 3 


0000 


II 


No system function. 


VVEL.KD 


[0224 3 


E93E 


II 


System return from int. 


VIMIRQ 


[02163 


E6F6 


IRQ 


System IRQ processor. 


VSEROR 


C020C3 


EA90 


II 


SIO. 


VSERIN 


C020A3 


EB1 1 


II 


SIO. 


VSEROC 


C020E3 


EAD1 


II 


SIO. 


VTIMR1 


[02103 


E7B2 


II 


PLA, RTI — ignore int. 


VTIMR2 


[02123 


E7B2 


II 


PLA, RTI — ignore int. 


VTIMR4 


[02143 


E7B2 


II 


*** doesn't matter *** 


VKEYBD 


C 0208 3 


FFBE 


II 


System keyboard int. handler 


VPRCED 


C 0202 3 


E7B2 


11 


PLA, RTI — ignore int. 


VINTER 


[ 0204 3 


E7B2 


II 


PLA, RTI — ignore int. 


VBREAK 


[02063 


E7B2 


ERK 


PLA, RTI — ignore int. 



After system initialization is complete, the interrupt enable 
situation is as follows: 

NMI VBLANK enabled, Display list disabled. 

IRQ CBREAK3 key and data key interrupts enabled, all others 
d isab led. 
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System timers 

There are five general purpose software timers plus a frame counter 
supported by the OS The timers are two bytes in length (lo,hi) and the 
frame counter RTCLOK C00123 is three bytes in length (hi/mid. lo). The 
timers count downward from any non-zero value to zero and upon 
reaching zero then either clear an associated flag or JSR through a 
RAM vector. The frame counter counts upward, wrapping to zero when it 
overflows. The table below shows the timers and the frame counter 



Flag/vector Use 

CDTMA1 C 02261 2 byte vector — SIO timeout. 

CDTMA2 C 0228] 2 byte vector 

CDTMF3 C022A3 1 byte flag 

CDTMF4 C022C3 1 byte flag 

CDTMF5 C022E j 1 byte flag 

3 byte frame counter. 

* These timers are maintained as part of every VBLANK interrupt (stage 
1 process); the other timers are subject to the critical section 
test (stage 2 process) which may defer their updating to a later 
VBLANK interrupt. 



characteristics: 
Timer name 

* CDTMV1 C02183 
CDTMV2 C 02 IAD 
CDTMV3 C021C3 
CDTMV4 C021E3 
CDTMV5 C02203 

* RTCLOK C00123 



Usage notes 

This subsection describes the "tricks" that must be known in 
order for the user to utilize interrupts in conjunction with the 
operating system. 

POKEY interrupt mask 

ANTIC (display list & vertical blank) and PIA (interrupt ?•< proceed 
lines) interrupts may be masked directly as described in the Hardware 
Manual. However, the POKEY interrupts (CBREAK3 key, data key., serial 
input ready, serial output ready, serial output done and timers 1,2 & 
4) are all masked by the eight bits of a single byte IRQEN CD20E3 
which happens to be a write-only register. Thus/ in order to 
selectively update individual interrupt mask bits, while not changing 
the other bits, we must maintain a current value of that register in 
RAM. The name of the variable used is POKMSK C00103 and it is used as 
shown in the examples below: 

EXAMPLE OF INTERRUPT ENABLE 

SEI i TO AVOID CONFLICT WITH IRQ . . . 

LDA POKMSK i ... PROCESSOR WHICH ALTERS VAR. 

OR A #$zx i ENABLE BIT(S). 

ST A POKMSK 

STA IRQEN i TO HARDWARE REG TOO. 
CLI 
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EXAMPLE OF INTERRUPT DISABLE 



SEI 
LDA 
AND 
STA 
STA 
CLI 



POKMSK i 
#*FF-xx ; 



TO AVOID CONFLICT WITH IRQ . . . 
. . . PROCESSOR WHICH ALTERS VAR. 
DISABLE BIT(S). 



POKMSK 
IRQEN 



TO HARDWARE REGISTER TOO. 



Note that the OS IRQ service routine uses and alters POKMSK* so 
alterations to the variable must be done with interrupts inhibited I 
done at the interrupt level there is no problem; as the I bit is 
already set; if done at a background level then the SEI and CLI 
instructions should be used as shown in the examples. 



Setting interrupt and timer vectors 

Because vertical blank interrupts are generally kept enabled so that 
the frame counter RTCLOK is maintained accurately/ there is a problem 
with setting the VBLANK vectors (VVBLKI %>. VVELKD) or the timer values 
(CDTMV1 through CDTMV5) directly. A VBLANK interrupt could occur when 
only one byte of the two byte value had been updated/ leading to 
undesired consequences. For this reason, the SETVBV CE45F] routine is 
provided to perform the desired update in safe manner. The calling 
sequence is shown below: 



A ■ update item indicator 

1-5 for timers 1-5. 

6 for immediate VBLANK vector VVBLKI. 

7 for deferred VELANK vector VVELKD. 
X = MSB of value to store. 

Y = LSB of value to store. 

JSR SETVBV 

The A/ X & Y registers may be altered. 

The display list interrupt will always be enabled on 
return* even if disabled upon entry. 



Note that it is possible that a vertical blank interrupt may be fully 
processed during a call to this routine. 

When working with the system timers, the vectors for timers 1 & 2 and 
the flags for timers 3/4 & 5 should be set while the associated timer 
is equal to zero; then the timer should be set to its (non-zero) 
va 1 ue. 
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Stack content at interrupt vector points 



The table belou, shows the stack content at every one of the RAM 
interrupt vector points: 

VDSLST C02003 
WBLKI C 0222 3 # 
CDTMA1 C022&T 
CDTMA2 C0228 3A 
WBLKD [02243 1 * 



VIMIRQ 
VSEROR 
VSERIN 
VSEROC 
VTIMR1 
VTIMR2 
VTIMR4 
VKEYBD 
VPRSED 
VINTER 
VBREAK 



[ 02163 * 
C020C3 # 
C 020 A 3 * 
C020E3 * 
C02103 
C02123 
C02143 
C02083 
C02023 
C0204 3 
C 0206 3 




list 


return, 


P 










immed . 


return, 


P, 


A, 


X, 


Y 




timer 1 


return, 


P, 


A, 


X, 


Y, 


return 


timer 2 


return, 


P, 


A, 


X, 


Y, 


return 


defer. 


return, 


P, 


A, 


X, 


Y 






IRQ immediate 
Serial out rdy 
Serial in rdy. 
Serial out cmp 
POKEY timer 1 
POKEY timer 2 
POKEY timer 4 
Keyboard data 
Serial proceed 
Serial interr. 
BRK instr. 



return/ P 

return, P 

return, P 

return, P 

return, P 

return, P 

return/ P 

return/ P 

return/ P 

return/ P 

return/ P 



Entries flagged with are initialized by 

power up; changing these vectors will alter 
properly. 



the operating system at 
system performance if not 



Miscellaneous considerations 

The following paragraphs list a set of miscellaneous considerations 
for the writer of an interrupt service routine. 

RESTRICTIONS ON CLEARING OF 'I' BIT 

Display list/ immediate vertical blank and system timer #1 routines 
should not clear the 6502 I bit. If the NMI leading to one of these 
routines occurred while an IRQ was being processed/ then clearing the 
I bit will cause the IRQ to re-interrupt with unknown result. 

The OS VBLANK processor carefully checks this condition after the 
stage 1 process and before the stage 2 process. 

INTERRUPT PROCESS TIME RESTRICTIONS 

If the serial I/O bus is being used/ then any user defined interrupt 
routine plus the stage 1 VBLANK routine should not exceed 400 usee. 
SIO sets the CRITIC flag while serial bus I/O is in progress 

INTERRUPT DELAY DUE TO "WAIT FOR SYNC" 

Whenever a key is read from the keyboard/ the Keyboard handler sets 
WSYNC CD40AD repeatedly while generating the audible click on the 
console speaker. A problem occurs when interrupts are generated during 
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the wait for sync period; the processing of such interrupts will be 
delayed by one horizontal scan line. Since this condition cannot be 
prevented; a solution available to the user is to examine the line 
count VCOUNT CD40BD and delay interrupt processing by one line when no 
WSYNC delay has occurred. 



Flowcharts 

The following pages contain process flowcharts showing the main events 
that occur in the NMI and IRQ interrupt processes. 
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7 System initialization 



Introduction 

System initialization takes place automatically in two circumstances: 
power up (also called coldstart) and the pressing of the CS/RESET3 key 
(warmstart). In addition/ there are vectors for these processes at 
E474 (CS/RESET3) and E477 (power up) so that they may be user 
initiated. 

The power up initialization process is a superset of the CS/RESET3 
initialization process; power up initializes both the OS and user RAM 
regions whereas CS/RESET3 initializes only the OS RAM region. In both 
cases the outer level software initialization entry points are called 
to allow the application to initialize its own variables. 

Pressing the S Reset key produces an NMI interrupt and does not 
perform a 6502 chip S RESET. If the processor is locked up/ S RESET 
may not be sufficient to unlock it, and the system may have to 
have power cycled to clear the problem. 

The remainder of section 7 will discuss the details of the power up 
and CS/RESET3 processes. Because they have many common functions 
(actually sharing common code)/ the power up process will be explained 
first and then the US/RESET} process will be explained in terms of its 
differences from the power up process. 



Power up initialization (coldstart) 

The functions listed below are performed/ in the order shown/ as part 
of the power up initialization process: 

1. The following 6502 processor functions are performed. 

IRQ interrupts are disabled using the SEI instruction. 
The decimal flag is cleared using the CLD instruction. 
The stack pointer is set to FF. 

2. The warmstart flag WARMST [00083 is set to 0 (false). 

3. A test is made to see if a diagnostic cartridge is in the "A" slot: 

Cartridge address BFFC ■ 00? 
The memory at BFFC is not RAM? 
Bit-7 of the byte at BFFD = 1? 

If all of the above tests are true/ then control is passed to the 
diagnostic cartridge via the vector at BFFE; no return is expected. 

4. The lowest memory address containing non-RAM is determined by 
testing the first byte of every 4K "block" to see if the content 
can be complemented. If it can be complemented/ then the original 
value is restored and testing continues; if it can't be 
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complemented/ it is assumed to be the first non-RAM address in the 
system. The MSB of the address is stored temporarily in TRAMSZ 
[0006 3. 



5. Zero is stored to all of the hardware register addresses shown 
below (most of which aren't decoded by the hardware): 

DOOO through DOFF 
D200 through D2FF 
D300 through D3FF 
D400 through D4FF 

6. RAM is cleared from location 0008 to the address determined in step 
4 above. 



7. The default value for the "non-cartridge" control vector DOSVEC 
[000A3 is set to point to the blackboard routine. At the end of 
initialization* control is passed through this vector if a 
cartridge does not take control. 

8. The coldstart flag COLDST [0244] is set to -J (local use). 

9. The screen margins are set; left margin = 2/ right margin = 39 for 
a 38 character physical line (the maximum line size of 40 
characters would be obtained by setting the margins to 0 & 39). The 
left margin is inset because many TV sets are manufactured such 
that the two leftmost columns of the video picture are not entirely 
visible on the screen. 



10. The interrupt RAM vectors VDSLST [02003 through WBLKD C02243 are 
initialized/ see section 6 for the initialization values. 

11. Portions of the OS RAM are set to their required non-zero values 
as shown below: 

The CBREAK 3 key flag BRKKEY [00113 = -1 (false). 

The top of memory pointer MEMTGP C02E53 = the lowest non- RAM 
address (from step 4), MEMTOP will be altered later when the 
Screen Editor is OPENed in step 15. 



The bottom of memory pointer MEMLO C02E73 ■ 0700; MEMLO may be 
changed- later if there is either a disk or cassette boot 
ope rati on 

The following resident routines are called for initialization 
— Screen Editor, Display handler, Keyboard handler, Printer 
handler, Cassette handler.. Central I/O Monitor (CIO), Serial 
I/O Monitor (SIO) and the Interrupt processor. 

The START key is checked; and if pressed., the cassette boot 
request flag CKEY [004A3 is set 

12. 6502 IRQ interrupts are enabled using the CLI instruction. 
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13. The Devite Table HATABS C031A3 is initialized to point to the 
resident handlers. See section 9 for information relating to the 
device handler table. 

14. The cartridge slot addresses for cartridges "B" and "A" are 
examined to determine if cartridges are inserted, if RAM does not 
extend into the cartridge address space 

If the content of location 9FFC is zero, then a JSR is executed 
through the vector at 9FFE, thus initializing cartridge "B". The 
cartridge is expected to return. 

If the content of location BFFC is zero, then a JSR is executed 
through the vector at BFFE, thus initializing cartridge !, A ,: . The 
cartridge is expected to return. 

15. IOCB #0 is setup for an OPEN of the Screen Editor (E) and the OPEN 
is performed. The Screen Editor will use the highest portion of 
RAM for the screen and will adjust MEMTOP accordingly. If this 
operation should fail/ the entire initialization process is 
repeated. 

16. A delay is effected to assure that a VBLANK interrupt has 
occurred. This is done so that the screen will be established 
before continuing. 

17. If the cassette boot request flag is set (see step li above), then 
a cassette boot operation is attempted. See section 10 for details 
of the cassette boot operation. 

18. If any of the three conditions stated below exists, an attempt is 
made to boot from the disk. 

There are no cartridges in the slots 

Cartridge l4 B" is inserted and bit-0 of 9FFD is 1. 

Cartridge "A" is inserted and bit-0 of BFFD is 1. 

See section 10 for details of the disk boot operation. 

19. The coldstart flag COLDST is reset to indicate that the coldstart 
process went to completion. 

20. The initialization process is now complete, and the controlling 
application is now determined via the remaining steps. 

If there is an "A" cartridge inserted and bit-2 of EFFD is 1, then 
a JMP is executed through the vector at BFFA. 

Else/ if there is a "B " cartridge inserted and bit-2 of 9FFD is li 
then a JMP is executed through the vector at 9FP A. 
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Else a jump is executed through the vector DOSVEC which may point 
to the blackboard routine (default case)/ cassette booted software 
or disk booted software. DOSVEC may be altered by the booted 
software as explained in section 10. 

CS/ RESET 3 initial i ration (warmstart) 

The functions listed below are performed/ in the order shown/ as part 
of the CS/RESET3 initialization process: 

A. Same as power up step 1. 

B. The warmstart flag WAR MS T C 0008 3 is set to -1 (true). 

C. Same as power up steps 3 through 5. 

D. OS RAM is zeroed from locations 0200-03FF and 0010-007F. 

E. Same as power up steps 9 through 16. 

F. If a cassette boot was successfully completed during the power up 
initialization/ then a JSR is executed through the vector CASINI 
C0002D. See section 10.3 for details of the cassette boot process. 

G. Same as power up step IS/ except instead of booting the disk 
software/ a JSR is executed through the vector DOSINI C000C3 if the 
disk boot was successfully completed during the power up 
initialization. See section 10 for details of the disk boot 
process. 

H Same as power up steps 19 and 20. 

Note that the initialization procedures and main entries for all 
software entities are executed at every CS/RESET3 as well as at power 
up (see steps 14/ 17/ 18/ 20/ F and G). If the user supplied 
i n i t i a 1 i za t i on/ s tar t up code must behave differently in response to 
CS/RESET3 than it does to power up/ then the warmstart flag WARMST 
C0008D should be interrr oga t ed ; WARMST = 0 means power up entry/ else 
CS/RESET] entry. 
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8 Floating point arithmetic package 

This section describes the BCD floating point package that is 
resident in the OS ROM in both the models 400 and 800. 



Introduction 

The floating point package maintains numbers internally as 6 byte 
quantities; a 5 byte (10 BCD digit) mantissa with a 1 byte exponent. 
BCD internal representation was chosen so that decimal division would 
not lead to the rounding errors typically found in binary 
representation implementations. 

The package provides the following operations: 

ASCII to F. P. conversion. 

F. P. to ASCII conversion. 

Integer to F. P. conversion. 

F. P. to integer conversion. 

F. P. add; subtract; multiply and divide. 

F. P. logarithm/ exponentiation and polynomial evaluation. 
F. P. zero/ load, store and move. 

A floating point operation is performed by calling one of the provided 
routines (each at a fixed address in ROM) after having set one or more 
floating point pseudo registers in RAM. The result of the desired 
operation will also involve floating point pseudo registers. The 
primary pseudo registers are described below and their addresses given 
within the square brackets: 

FRO C00D41 = 6 byte internal form of f. p. number. 

FR1 C00E03 * 6 byte internal form of f. p. number. 

FLPTR COOFCH = 2 byte pointer (lo/hi) to a f.p. number. 

INBUFF C00F3D = 2 byte pointer (lo/hi) to an ASCII text buffer 

CIX C00F23 = 1 byte index, used as offset to buffer pointed to 

by INBUFF C00F21. 
LBUFF C05803 = result buffer for the FASC routine. 



Func t ions/cal ling sequences 

In the paragraphs that follow are the descriptions for all of the 
routines; unless specifically mentioned in the calling sequence, it is 
assumed that a pseudo register is not altered by a given routine. The 
numbers in square brackets Cxxxxl are the ROM addresses of the 
routines. 

ASCII to floating point conversion (AFP) 

Function: This routine takes an ASCII string as input and produces a 
floating point number in internal form. 
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Calling se que nee: 



INBUFF = pointer to buffer containing the ASCII 

representation of the number. 

CIX = the buffer offset to the first byte of the ASCII 
number. 

JSR AFP CD800D 

BCS first byte of ASCII number is invalid 

FRO = floating point number. 

CIX = the buffer offset to the first byte after the ASCII 

number. 



Algorithm: The routine takes bytes from the buffer until it encounters 
a byte which cannot be part of the number. The bytes scanned to that 
point are then converted to a floating point number. If the first byte 
encountered is invalid; the carry bit is set as a flag. 

Floating point to ASCII conversion (FASC) 

Function: This routine converts a floating point number from internal 
form to its ASCII representation. 

Calling sequence: 

FRO = floating point number. 

JSR FASC Z D8E6 3 

INBUFF = pointer to the first byte of the ASCII number. 
The last byte of the ASCII representation has the most 
significant bit (sign bit) set; no EOL follows. 

Algorithm: The routine converts the number from its internal floating 
point representation to a printable form (ATASCII). The pointer INBUFF 
will point to part of LBUFF, where the result is stored. 

Integer to floating point conversion (IFP) 

Function: This routine converts a two byte unsigned integer (0 to 
65535) to floating point internal representation. 

Calling sequence: 

FRO ■ integer (FRO+0 = LSB, FRO+1 = MSB). 
JSR IFP CD9AAD 

FRO = floating point representation of integer. 
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Floating point to integer conversion <FPI) 

Function: This routine converts a positive floating point number from 
its internal representation to the nearest two byte integer. 

Calling sequence: 

FRO = floating point number. 

JSR FPI CD9D2 3 

BCS f. p. number is negative or >= 65535. 5 

FRO = two byte integer (FRO+O * LSB, FRO+1 « MSB). 

Algorithm: The routine performs true rounding* not truncation; during 
the conversion process. 

Floating point addition (FADD) 

Function: This routine adds two floating point numbers and checks the 
result for out of range. 



Call ing 


sequence: 


FRO 
FRl 


= floating point number. 
= floating point number. 


JSR 
BCS 


FADD CDA663 

out of range result. 


FRO 
FRl 


« result of FRO + FRl. 
is altered. 


Fl oat ing 


point subtraction (FSUB) 


Function: This routine subtracts two 
the result for out of range 


Call ing 


sequence: 


FRO 
FRl 


= floating point minuend. 
= floating point subtrahend 


JSR 
BCS 


FSUB CDA60 3 

out of range result. 


FRO 
FRl 


= result of FRO - FRl. 
is altered. 


Floating 


point multiplication (FMUL) 



Function: This routine multiplies two floating point numbers and 
checks the result for out of range. 
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Calling sequence: 

FRO = floating point multiplier. 
FR1 = floating point multiplicand. 

JSR FMUL CDADBD 

BCS out of range result. 

FRO = result of FRO * FR 1 . 
FR1 is altered. 

Floating point division (FDIV) 

Function: This routine divides two floating point numbers and check 
for division by zero and for result out of range. 

Calling sequence: 

FRO = floating point dividend. 
FR 1 = floating point divisor. 

JSR FDIV CDB28D 

BCS out of range result or divisor is zero. 

FRO = result of FRO / FR 1 . 
FR 1 is altered. 

Floating point logarithms < LOG ?y LOGIC) 

Function: These routines take the natural or base 10 logarithms of 
floating point number. 

Calling sequence: 

FRO ■ floating point number. 

JSR LOG CDECD3 for natural logarithm 

or 

JSR L0G10 CDED1 3 for base 10 logarithm 

BCS negative number or overflow. 

FRO = floating point logarithm. 
FR 1 is altered. 

Algorithm: Both logarithms are first computed as base 10 logarithms 
using a 10 term polynomial approximation; the natural logarithm is 
computed by dividing the base 10 result by the constant LOGlO(e). 

The logarithm of a number Z is computed as follows: 

F * (10 ** Y) = Z where 1 <= F < 10 (normalization). 
L = LOGIO(F) by 10 term polynomial approximation. 
LOGIO(Z) = Y + L. 
LOG(Z) = LOGIO(Z) / LOGlO(e). 
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NOTE: This routine does not return an error if the number input is 
zero; the LOGIO result in this case is approximately -129. 5* 
which is not useful. 

Floating point exponentiation (EXP and EXPIO) 

Function: This routine exponentiates. 

Calling sequence: 

FRO = floating point exponent (Z). 

JSR EXP CDDC03 for e ** Z 

or 

JSR EXPIO CDDCCD for 10 ** Z 

BCS overflow. 

FRO = floating point result. 
FR1 is altered. 

Algorithm: Both exponentials are computed internally as base 10. with 
the base e exponential using the identity: 

e ** X = 10**( X * LOGlO(e) ). 

The base 10 exponential is evaluated in two parts using the identity: 

10 ** X ■ 10 ** (I + F > = (10 ** I) * (10 ** F) — where I is the 
integer portion of X and F is the fraction. 

The term 10 ** F is evaluated using a polynomial approximation; and iO 
** I is a straightforward modification to the floating point exponent. 

Floating point polynomial evaluation (PLYEVL) 

Function: This routine performs an n degree polynomial evaluation. 

Calling sequence: 

X/Y = pointer (X = LSB ) to list of f.p. coefficients (A(i)> 

ordered from high order to low order. 
A = number of coefficients in list. 
FRO ■ floating point independent variable (Z). 

JSR PLYEVL CDD401 

BCS overflow or other error. 

FRO - result of A(n)*Z**n + ACft-1 >*Z**n-l ... + A(1)*Z * 

A(0>. 
FR1 is altered. 

Algorithm: The polynomial P(Z) = SUM < i *0 to n) <A(i>*Z**i> is computed 
using the standard method shown below: 
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P(Z) = <...<A(n>*Z + A(n-1 > >*Z + ... + A< 1 > >*Z ♦ A<0) 

Clear FRO (ZFRO) 

Function: This routine sets the contents of pseudo register FRO 
to all zeroes. 

Calling sequence: 

JSR ZFRO CDA443 

FRO = zero. 

Clear page zero floating point number (ZF1) 

Function: This routine sets the contents of a zero page floating point 
number to all zeroes. 

Calling sequence: 

X = zero page address of f.p. number to clear. 



Load floating point number to FRO (FLDOR and FLDOP ) 

Function: These routines load pseudo register FRO mith the floating 
point number specified by the calling sequence. 

Calling sequences: 

Xi Y = pointer (X = LSB ) to f.p. number. 



JSR 



ZF1 CDA46D 



zero page f.p. number(X) = zero. 



JSR 



FLDOR CDD89 ] 



or 



FLPTR 



pointer to f. p. number. 



JSR 



FLDOP CDD8D3 



FRO = floating point number (in either case). 
FLPTR = pointer to f.p. number (in either cas 



Load floating point number to FR1 (FLD1R and FLD1P) 



Function: These routines load pseudo register FR i with the 
floating point number specified by the calling sequence. 
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Calling sequences: 

As in prior description* except the result goes to FRl 
instead of FRO. FLDIR CDD983 and FLD1P CDD9C 3 

Store floating point number from FRO (FSTOR and FSTOP ) 

Function: These routines store the contents of pseudo register FRO to 
the address specified by the calling sequence: 

Calling sequence: 

As in prior descriptions/ except the floating point number is 
stored from FRO rather than loaded to FRO. FSTOR CDDA7D and FSTOP 
CDDABD. 

Move floating point number from FRO to FRl (FMOVE) 

Function: This routine moves the floating point number in FRO to 
pseudo register FRl. 

Calling sequence: 

JSR FMOVE CDDB63 

FRl = FRO (FRO remains unchanged). 

Resource utilization 

The floating point package uses the following RAM locations in the 
course of performing the functions described in this section: 

00D4 through OOFF 
057E through 05FF 

If the floating package is not utilized, all of those locations are 
available for the user program. 

Implementation detai Is 

Floating point numbers are maintained internally as 6 byte quantities, 
with 5 bytes < 10 BCD digits) of mantissa and 1 byte of exponent. The 
mantissa is always normalized such that the most significant byte is 
non-zero (note "byte" and not "BCD digit"). 

The most significant bit of the exponent byte provides the sign for 
the mantissa, O for positive and 1 for negative. The remaining 7 bits 
of the exponent byte provide the exponent in excess 64 notation; the 
resulting number represents powers of 100 decimal (not powers of 10). 
A result of this storage format is that the mantissa holds 10 BCD 
digits when the value of the exponent is an even power of 10 and holds 
9 BCD digits when the value of the exponent is an odd power of 10. 
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The implied decimal point is always to the immediate right of the 
first byte so that an exponent that is less than 64 indicates a number 
less than 1 and an exponent greater than or equal to 64 represents a 
number greater than or equal to 1. 

Zero is represented by a zero mantissa and a zero exponent. In testing 
for a result from any of the standard routines., it is sufficient to 
test either the exponent or the first mantissa byte for zero. 

The absolute value of floating point numbers must be greater than 
10**-98 and less than 10**+98 or be equal to zero. There is perfect 
symmetry between positive and negative numbers with the exception that 
negative zero is never generated. 

Although the precision of all computations is maintained at 9 or 10 
decimal digits., the accuracy is somewhat less for those functions 
involving polynomial approxi ma tions (logarithm and exponentiation). 
Also, the problems inherent in all floating point systems are present 
here/ for example: subtracting two very nearly equal numbers, adding 
numbers of disparate magnitude, or successions of any operation will 
all result in a loss of significant digits. For some types of 
applications an analysis of the data range and the order of evaluation 
of expressions may be required. 

The remainder of this section will give some examples of the internal 
representation of some floating point numbers as an aid to 
understanding the storage format. All numbers prior to this point have 
been expressed in decimal notation, but the examples will use 
hexadecimal notation (note that 64 decimal, the excess number of the 
exponent, is 40 when expressed in hexadecimal). 



Number : 


+0. 02 


= 2 * 


10**-2 


= 2 * 


100**-1 








Stored : 


3F 02 


00 00 


00 00 


(f . p. 


exponent = 


40 




1 ) 


Numb er : 


-0. 02 


= -2 * 


■ 10**-2 


as —2 


* 100**-1 








Stored : 


BF 02 


00 00 


00 00 


(f P . 


exponent = 


80 




40 


Numb er : 


+37. 0 


= 3. 7 


•* 10-a-* 1 


= 37 


* 100**0 








Stored : 


40 37 


00 00 


00 00 


(f . p. 


exponent = 


40 




0) 


Number : 


-4. 60312486 


* 10**11 = - 


46. 03. . . * 


100**5 


Stored : 


C5 46 


03 01 


24 86 


(f . p. 


exponent = 


80 


+ 


40 


Number : 


0. 0 
















Stored : 


00 00 


00 00 


00 00 


(spec 


ial case) 









/ 
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9 - Adding new device handlers/peripherals 

This section describes the interface requirements for a non resident- 
device handler that is to be accessed via the Central I/O utility 
(CIO); further, the Serial bus I/O utility (SIO) interface is defined 
for those handlers which utilize the Serial I/O bus. 

« 

The I/O subsystem is organized with three levels of software betyppn 
the user and the hardware. At the outer level is CIO, which performs 
the following functions: 

Logical device name to device handler mapping (on OPEN). 
I/O Control Block (IOCB) maintenance. 
Logical record handling. 
User buffer handling. 

Below CIO are the individual device handlers, which perform the 
fol lowing functions: 

Device initialization on power up and CS/RESET3 . 
Device dependent support of OPEN and CLOSE commands. 
Byte at a time data input and output. 
Device dependent special operations. 
Device dependent command support. 
Device data buffer management. 

At the bottom level (for Serial I/O bus peripheral handlers) is SIO, 
which performs the following functions. 

Control of all Serial bus I/O, conforming to the bus protocol as 
described in section 9. 

Bus operation retries on errors. 

Return of unified error statuses on error conditions. 

At each interface there is a separate control structure used for 
communication/ as shown below: 

User /C 10 I/O Control Block (IOCB) 

CIO/Handler Zero page IOCB (ZIOCB) 

Handler/SIO Device Control Block (DCB) 

ese relationships are shown graphically on the next page. 
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I/O SU3SYSTEM FLOW DIAGRAM 
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! Device 

! Table 
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i program ! 
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+ + 
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DCB 



+ 
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Pr inter 
Hand 1 er 



+ 

Cassette ! 
Hand 1 er I 



+ i_ 

iDisk File ! 

Manager ! 
+ + 



h 



+ 



Han d 1 er 



-r- + 

! Keyboard! 
i Hand I er ! 



Disk 
Ha rid I er 



DCB 



+ 

+ 

! SIO 
! Utility 
4- 



Where: shows a control path. 

shows the data structure required for a path. 

Note the following: 

1. The Keyboard/Disp lay /"Screen Editor handlers don't use 
SIO. 

2. The Disk handier is not callable directly from CIO 

3. The DCB is shown twice in the diagram 
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Device Table 

The Device Table is a RAM resident table that contains the single 
character device name (e. g. k, D, C, etc. ) and the handler address for 
each of the handlers known to CIO. The table is initialized at power 
up (and CS/RESET3) to contain entries for the following resident 
handlers: Keyboard <K>, Display <S>, Screen Editor <E>, Cassette (C) 
and Printer (P). To install a new handler, some procedure must insert 
a Device Table entry after the table is initialized. 

The table format is shown below: 



+ + -+ 

HATAES C031A] ! device name ; { 

4 + « 

i handler vector \ 4— one entry 
+ + { 

I table address ! i 

+ + _^ 

! more ! 

== = 

i entries J 



+ + 

i zero fill to ! 



! end of table ! 
+ + 



The table is 38 bytes long and will hold a maximum of 12 entries, with 
the last two bytes being zero. CIO scans the table from the end to the 
beginning (high to low address); so, in the case of multiple 
occurrences of a device name, the entry nearest the end of the table 
will take precedence. 

The device name for each entry it a single ATASC 1 1 character, and the 
handler address points to the handler's vector table, which will be 
described in the following section. 



C ID/hand ler interface 

This section describes the interface between the Central I/O utility 
and the individual device handlers that are represented in the Device 
Table *as described in the preceding section). 



Calling mechanism 

Each handler has a vector table as shown below: 
space 1 ; need 16 

+ ^ 

+ OPEN vector * (low address) 

+ h 

+ CLOSE vector + 
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+ + 

+ GETBYTE vector f 
+ + 

+ PUTBYTE vector + 
+ + 

+ GETSTAT vector + 
+ SPECIAL vector + 
+ + 

♦ JMP init code + 

+ + < h i g h ad dre ss > 

+ . + 

The Device Table entry for the handler points to the first byte of the 
vector table. 

The first six entries in the table are vectors (lo/hi) which contain 
the address - 1 of the handler routine which handles the indicated 
function. The seventh entry is a 6502 JMP instruction to the handler 
initialization routine. CIO uses oni\j the addresses contained in this 
table for handler entry; each user/CIO command translates to one or 
more calls to one of the handler entries defined in the vector table. 

The vector table provides to CIO the handler addresses for certain 
fixed functions to be performed; but/ in addition/ operation 
parameters must be passed for most functions. Parameter passing is 
accomplished using the 6502 A/ X and Y registers and an IOCB in page 0 
named ZIOCB C0020D. In general/ register A is used to pass data, 
register X contains the index to the originating IOCB and register Y 
is used to pass status information to CIO. The zero page IOCB is a 
copy of the originating IOCE; but in the course of processing some 
commands/ CIO may alter the buffer address and buffer length 
parameters in ZIOCB (but not in the originating IOCB). see section 
5.2.2 for information relating to the originating IOCB. 

Reference Appendix B for the standard status byte values to be 
returned to CIO in register Y. 

The following sections will describe the CIO/handler interface for 
each of the vectors in the handler vector table. 



Handler initialization 

This entry doesn't appear to have any function for non-resident 
handlers due to a bug in the current OS — the Device Table is 
cleared in response to both CS/RESET3 and power up/ instead of just 
power up/ thus preventing this entry point from ever being 
called. The rest of this section discusses the intended/ but 
not implemented/ use of this entry point; conformation would be 
in order to allow compatibility with possible corrected versions 
of the OS in the future. 

The entry was to have been called on all occurrences of power up and 
CS/RESETD; the handler is to perform initialization of its hardware 
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and RAM data so as to assure proper processing of all CIO commands 
that follow. 

Functions supported 

This section describes the functions associated with the first six 
vectors from the handler vector table. A brief/ device independent, 
description of the CIO/handler interface and recommended actions are 
given for each function vector. 

OPEN 

This entry is called in response to an OPEN command to CIO; the 
handler is expected to validate the OPEN parameters and perform any 
required device initialization associated with a device OPEN. 

At handler entry/ the following parameters may be of interest: 

X = index to originating IOCB. 

Y = $92 (status = function not implemented by handler). 

ICDNOZ C0021D = device number (1-4/ for multiple device 

hand 1 er s ) . 

ICBALZ/ICBAHZ C0024/0025D « address of device/filename 

specification. 

ICAX 1 Z / ICAX2Z C002A/0C2BD = device specific information 

The handler will attempt to perform the indicated OPEN and will 
indicate the status of the operation by the value of the Y register. 
The responsibility for checking for multiple OPENs to the same device 
or file/ where it is illegal/ lies with the handler. 

CLOSE 

This entry is called in response to a CLOSE command to CIO; the 
handler is expected to release any held resources that relate 
specifically to that device/filename/ and for output files to; i) send 
any data remaining in handler buffers to the device/ 2) mark the end 
of file/ and 3) update any associated directories/ allocation maps, 
etc. 

At handler entry/ the following parameters may be of interest: 
X = index to originating IOCB. 

Y *= $92 (status = function not implemented by handler). 

ICDNOZ C0021D = device number (1-4/ for multiple device 

hand 1 er s ) . 

ICAX1Z/ICAX2Z C002A/002B3 = device specific information 

The handler will attempt to perform the indicated CLOSE and will 
indicate the status of the operation by the value of the Y register. 
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CIO will release the associated IOCB after the handler returns, 
regardless of the operation status value. 

GETBYTE 

This entry is called in response to a GET CHARACTERS or GET RECORD 
command to CIO. The handler is expected to return a single byte in the 

A register or return an error status in the Y register. 

» 

At handler entry, the following parameters may be of interest: 
X « index to originating IOCB. 

Y = $92 (status « function not implemented by handler). 

ICDNOZ [00213 = device number (1-4, for multiple device handlers). 
ICAX1Z/ ICAX2Z C002A/002BD = device specific information. 

The handler will 'obtain a data byte directly from the device or from a 
handler maintained buffer and return to CIO with the byte in the A 
register and the operation status in the Y register. 

Handlers which do not have short timeouts associated with the reading 
of data (such as the Keyboard and Cassette handlers), must monitor the 
[ BREAK D key flag BRKKEY [001111 and return with a status of *B0 wqen a 
[BREAK3 condition occurs. See section 4 E5 and section 12 for a 
discussion of [BREAK] key monitoring. 

CIO checks for reads from device/files that have not been OPENed or 
OPENed for output only; the handler will not be called in those cases. 

PUTEYTE 



This entry is called in response to a PUT CHARACTERS or PUT RECORD 
command to CIO. The handler is expected to accept a single byte in the 
A register or return an error status in the Y register. 



At handier entry/ the following parameters may be of interest: 
X = index to originating IOCB. 

Y = $92 (status = function not implemented by handler). 
A - data byte. 

ICDNOZ [00213 device number (1-4, for multiple device 

handlers ) . 

ICAX1Z/ICAX2Z [C02A/002B] = device specific information. 

The handler will send the data byte directly to the device or to a 
handler maintained buffer and return to CIO with the operation status 
in the Y register. If a handler maintained buffer fills, the handier 
will send the buffered data to the device before returning to CIO. 

CIO checks for writes to device/files that have not been OPENed or 
OPENed for input only; the handler will not be called in those cases. 
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Now that the normal operation of PUTBYTE has been defined/ a special 
case must be added; any handler that will operate within the 
environment of the 8K BASIC language interpreter has a different set 
of rules. Because BASIC can call the handler PUTBYTE entry directly, 
without going through CIO/ the zero-page IOCB (ZIOCB) may or may not 
have a relation to the PUTBYTE call; thus the handler must use the 
outer level IOCB to obtain any information that would normally be 
obtained from ZIOCB. Note also in this case that the OPEN protection 
normally provided by CIO is bypassed (i.e. PUTBYTE to a non-OPEN 
device/file and PUTEYTE to a read-only OPEN). 

OETSTAT 

This entry is called in response to a GET STATUS command to CIO. The 
handler is expected to return four bytes of status to memory or return 
an error status in the Y register. 

At handler entry/ the following parameters may be of interest: 

X ■ index to originating IOCB. Y = $92 (status ~ function not 
implemented by handler). 

ICDNOZ [00213 = device number <i-4/ for multiple device handlers ). 

ICBALZ/ICBAHZ [0024/00253 - address of 

device /filename specification. 
ICAX12/ICAX2Z 

C002A/002E 3 - device specific information. 

The handler will get device status information from the device 
controller and put the status bytes in DVSTAT C02EA3 through D VST AT +3 
and return to CIO with the operation status in register Y. 

The IOCB need not be OPENed nor CLOSEd in order for the user to 
request CIO to perform a GET STATUS operation., the handler must check 
where there are restrictions. See section 5.2.3 for a discus? ion of 
the CIO actions involved with a GET STATUS operation using both OPEN 
and CLOSEd IOCBs/ and note the impact of this on the use of the buffer 
address parameter. 

SPECIAL 

This handler entry is used to support all functions not handled by the 
other entry points/ such as disk file RENAME, display DPxAW/ etc 
Specifically/ if the IOCB command byte value is greater than fcODi then 
CIO will use the SPECIAL entry point The handler must interrogate the 
command byte to determine if the requested operation is supported 

At handler entry/ the following parameters may be of interest: 

X = index to originating IOCB 

Y = *92 (status = function not implemented by handler). 

ICDNOZ C00213 = device number (1-4/ for multiple device 

hand 1 er s ) . 
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ICCOMZ C00223 
ICBALZ/ICBALH 
ICBLLZ/ICBLHZ 
ICAX1Z/ICAX2Z 



= command byte. 

C 0024/00253 = buffer address. 
£0028/0029 3 = buffer length. 
C002A/002B3 = device specific 



information 



The handler will perform the indicated operation/ if possible* and 
return to CIO with the operation status in register Y. 

The IOCB need not be OPENed nor CLOSEd in order for the user to 
request CIO to perform a SPECIAL operation; the handler must check 
where there are restrictions. See section 5 for a discussion of the 
CIO actions involved with a SPECIAL operation using both OPEN and 
CLOSEd IOCBs » and note the impact of this on the use of the buffer 
address parameter. 



Error hand ling 

Error handling has been simplified somewhat by having CIO handle outer 

level errors and having SIO handle Serial bus errors; leaving the 

handler to process the remaining errors. These errors include: 

Out of range parameters. 
C BREAK] key abort. 
Invalid command. 
Read after end of file. 

The current handlers respond to errors using the following guidelines: 

Keep the recovery simple (and therefore predictable & repeatable). 

Do not interact directly with the user for recovery instructions. 

Lose as little data as possible. 

hake all attempts to maintain the integrity of file oriented 
device storage — this involves the initial design of the 
structural elements as well as error recovery techniques. 



Resource allocation 

Non-resident handlers needing code and/or data space in RAM should use 
the techniques listed below* in order to assure nonconflict with other 
parts of the OS., including other nonresident handlers. 

ZERO-PAGE RAM 

There are no spare bytes of zero page RAM* and even if there were* 
there is no allocation scheme to support multiple program assignment 
of the spares. Therefore* the non-resident handler must save and 
restore the bytes of zero-page RAM it is going to use. The bytes to 
use must be chosen carefully* according to the following criteria: 
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The bytes may not be accessed by an interrupt routine. 

The bytes may not be accessed by any non-interrup t code between 
the time the handler modifies the bytes and then restores the 
original values. 

A simple save/restore technique would utilize the stack in a 
manner similar to that shown below: 

; (for example) 
; SAVE ON STACK. 



LDA 


COLCRS 


PHA 




LDA 


COLCRS+1 


PHA 




LDA 


HPOINT 


STA 


COLCRS 


LDA 


HPOINT+1 


STA 


COLCRS+1 


XXX 


(COLCRS), Y 


PLA 




STA 


COLCRS+l 


PLA 




STA 


COLCRS 



i HANDLER '5 POINTER 



; DO YOUR POINTER THING, 
i RESTORE OLD DATA. 



Note that for the example above, it would not be judiciou, to call the 
Display handler or the Screen Editor before restorxng the original 
value of COLCRS, as COLCRS is a variable used by those routines 

NON- ZERO-PAGE RAM 

Again, there is no allocation scheme to support the assignment of 
fixed regions of non-zero-page RAM to any specific process, so the 
handler has three choices: 

1. Make a dynamic allocation at initialization time by altering 
MEMLO C02E73. 

2 Include the variables with the handler for RAM resident 
handlers; this still involves altering MEMLO at the time the 
handler is booted. 

3 If the handler is to be replacing one of the resident handlers 
by removing the resident handler's entry in the Device Table, 
then the new handler may use any RAM that the formerly resident 
handler would have used. 

STACK SPACE 

In normal situations there are no restrictions on the use of th» «tJic* 
by a handler; however, if the handler is planning on pushing "or.^than 
a couple of dozen bytes to the stack, it should do a stack overflow 
test and always leave stack space for interrupt processing 
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Hand ler /SIO interface 

This section describes the interface between serial bus device 
handlers and the serial bus I/O utility (SIO). SIO completely handles 
all bus transactions following the device independent bus protocol. 
SIO is responsible for the following functions: 

Bus data format and timing from computer end 

Error detection/ retries and statuses. 

Bus timeout. 

Transfer of data between the bus and the caller's buffer. 



Calling mechanism 

SIO has a single entry point 5I0V EE4d9j for all operations, and 611 

parameters passed to SIO are contained in the Device Control Block 

(DCE) £0300 j , which contains the following bytes: 

DEVICE BUS I. D. — DDEVIC C 030011 

The bus I.D. of the device is set by the handler prior to calling SID 
(see Appendix I). 

DEVICE UNIT # — DUN I T C030i] 

This byte indicates which of n units of a given device type to access 
and is set by the handler prior to calling SIO/ in general this value 
comes from ICDNOZ. SIO will access the bus device whose address is 
equal to the value of DDEVIC plus DUN IT minus one (the lowest unit 
number is normally equal to one). 

DEVICE COMMAND — DCGMND C 0302 3 

This byte is set by the handler prior to calling SIO and will be sent 
to the bus device as part of the command frame (see section 9 for a 
discussion of the command frame., and Appendix I for device command 
byte values). 

DEVICE STATUS — DSTATS CC3C33 

This byte is bi-directional/ the handler wi I ) use it to indicate to 
SIO what to do after the command frame is sent and acknowledged., ©nd 
SIO will use it to indicate to the handler the status of the requested 
operat i on. 

Prior to an SIO call: 
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7 0 

-i 1 s 1 J 1 i- — + 

iWIRi unused i 

Where: W/ R = O/O indicates no data transfer is associated with the 

op era t i on. 

0/1 indicates a data frame is expected from the device. 
1/0 indicates a data frame is to be sent to the device. 
1/1 is invalid. 

After an SIO call: 

7 0 

4- — — I — H 1 — -i — -i 1 1- 

I status code I 

_j ^ — .j j- — K — I h--t- 

See Appendix C for the possible SIO operation status codes. 
HANDLER BUFFER ADDRESS — DBUFLO /DBUFH I C0304/0305D 

This two byte pointer is set by the handler and indicates the source 
or destination buffer for device data or status information. 

DEVICE TIMEOUT — DTIMLO C 03063 

This byte is set by the handler and specifies the device timeout time 
in units of 64/60ths of a second. For example/ a count of 6 specifies 
a timeout of 6.4 seconds. 

BUFFER LENGTH/BYTE COUNT — DBYTLO/DBYTH I [0308/03093 

This two byte count is set by the handler and indicates the number of 
data bytes to be transferred into or out of the buffer/ for the 
current operation. This parameter is not required if the STATUS byte W 
and R bits are both zero, indicating that no data transfer is to take 
place. 

There is a bug in SIO that causes incorrect actions when the 1-ast 
byte of a buffer is in a memory address ending in $FF > such as 
13FF* 42FFi etc. 

AUXILIARY INFORMATION — DAUX1/DAUX2 t 030 A/ 03GB 3 

These two bytes are set by the handler and are included in the bus 
command frame by SIO/ they have device specific meanings. 

Functions supported 

SIO does not examine the COMMAND byte it sends to the device, as 
all bus transactions are expected to conform to a universal 
protocol u.'hjch includes 3 forms. These forms are stated below 
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(as seen from the computer): 

Send command frame. 

Send command frame and send data frame. 

Send command frame and receive data frame. 

The command form is selected purely by the values of the W and R 
bits in the STATUS byte as described earlier. 



Error handling 

SIO does the bulk of the error handling for the handler/ in terms of 
Serial bus errors/ as indicated below: 

Eus timeout — SIO provides a uniform command frame and data frame ACK 
byte timeout of l/60th of a second - 0 / + l/60th. The handler 
specifies the maximum COMPLETE byte timeout value in DTIMLO as 
described earlier. 

Bus errors — SIO detects and reports UART overrun and framing errors; 
the sensing of these errors in any received byte will cause the entire 
associated frame to be considered bad. 

Data frame checksum error — SIO validates the checksum on all 
received data frames and generates a checksum for all transmitted 
frames. 

Invalid response from device — In addition to the error conditions 
stated above/ SIO checks that the ACK and COMPLETE responses are 
proper (ACK = *41 and COMPLETE = *43 ) . ACK stands for acknowledge. 

Bus operation retries — SIO will attempt one complete command retry 
if the first attempt is not error free/ where a complete command try 
consists of up to 14 attempts to send (and acknowledge) a command 
frame/ followed by a single attempt to receivethe COMPLETE code and 

possibly a 
data frame. 

There is a bug in the retry logic for data writes/ such that if the 
command frame is ACKed by the controller, but the data frame is not 
ACKed, then SIO will retry indefinitely. 

Unified error status codes — SIO provides device independent error 
codes as shown in Appendix C. 



Serial I/O bus characteristics and protocol 

This section describes the electrical characteristics of the ATARI 400 
and ATARI 800 Personal Computer Systems serial bus/ the use of the bus 
to send bytes of data/ the organization of the bytes as "frames" 
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(records)* and the overall command sequences which utilize frames and 
response bytes to provide computer/peripheral communication. 

Hard wa re/electrical characteristics 

The ATARI 400 and the ATARI 800 Personal Computer Systems communicate 
with peripheral devices over a 19,200 baud asynchronous serial port. 
The serial port consists of a serial DATA OUT (transmission) line, a 
serial DATA IN (receiver) line and other miscellaneous control lines. 

Data is transmitted and received as 8 bits of serial data (LSB sent 
first) preceded by a logic zero start bit and succeeded by a logic one 
stop bit. The serial DATA OUT is transmitted as positive logic (+4v = 
one/true/high, Ov = zero/false/low). The serial DATA OUT line always 
assumes its new state when the serial CLOCK OUT line goes high; CLOCK 
OUT then goes low in the center of the DATA OUT bit time. 

An end view of the Serial bus connector at the computer or peripheral 

is shown below (the cable connectors would of course be a mirror 
imag e ) : 

2 4 6 8 10 12 

o o o o o o 

0 o o o o o o 

1 3 5 7 9 11 13 



where: 1 ■ computer CLOCK IN. 

2 = computer CLOCK OUT. 

3 = computer DATA IN. 

4 = GND. 

5 = computer DATA OUT. 

6 = GND. 

7 = COMMAND-. 

8 = MOTOR CONTROL. 

9 - PROCEED-. 

10 = +5v/READY. 

11 = computer AUDIO IN. 

12 = + 12v. 

13 = INTERRUPT-. 

CLOCK IN is not used by the present OS and peripherals. This line can 
be used in future synchronous communications schemes. 

CLOCK OUT is the serial bus clock. CLOCK OUT goes high at the start o 
each DATA OUT bit and returns to low in the middle of each bit. 

DATA IN is the serial bus data line to the computer. 

Pin 4 GND is the s i gna 1 /sh i e 1 d ground line. 
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DATA OUT is the serial bus data line from the computer. 
Pin 6 GND is the si gna 1 /sh i e 1 d ground line 

COMMAND- is normally high and goes lou» when a command frame is being 
sent from the computer. 

MOTOR CONTROL is the cassette motor control line (high^on, low= off). 

PROCEED- is not used by the present OS and peripherals < this line 
is pulled high. 

+5v/READY indicates that the computer is turned on and ready. This 
line may also be used as a +5 volt supply of 50mA current rating 
for ATARI peripherals only. 

AUDIO IN accepts an audio signal from the cassette. 

+ 12V is a -+12 volt supply of unknown current rating for ATARI 
peripherals only. 

INTERRUPT- is not used by the present OS and peripherals ( this line 
is puiled high 

There are r»o pin r ea s s i g nmen t s made in the Serial bus cable/ so pin 3: 
the computer's DATA IN line, is the peripheral's data output line; and 
similarly for pin 5 

Serial port electrical specifications 

Peripheral input' 

VI H = 2 Ov mm. 
VI L - 0. 4v ma x . 

I1H = 20ua. max. @ V1H = 2. Ov 
I1L m Sua. max. £ V1L = . 4v 

Peripheral output (open collector bipolar): 

VOL = 0 4v max. £ 1.6 ma. 

VOK - 4. 5v min with external lOOKohm pull-up 
Vcc /READY input. 

V1H = 2 Ov min. £ I1H - Ima. max. 
V1L = O 4v ma x 

Input goes to logic zero when open. 
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Bus commands 

The bus protocol specifies that all commands must originate from the 
computer, and that peripherals will present data on the bus only when 
commanded to. Every bus operation will go to completion before 
another bus operation is initiated (no overlap). An error detected at 
any point in the command sequence will abort the entire sequence. 

A bus operation consists of the following elements: 

Command frame from the computer. 

Acknowledgement <ACK) from the peripheral. 

Optional data frame to or from the computer. 

Operation complete (COMPLETE) from the peripheral. 
COMMAND FRAME 

The serial bus protocol provides for three types of commands: i) data 
send, 2) data receive and 3) immediate (no data — command only). 
There is a common element in ail three types, a command frame 
consisting of five bytes of information sent from the computer while 
the COMMAND- line is held low. The format of the command frame is 
shown below: 

4- + 

! device I. D. ! 
+ + 

I command { 
+ + 

! aux i 1 1 lar y #1 \ 
\ auxilliary #2 I 
! checksum { 

The device I.D. specifies which of the serial bus devices is being 
addressed (see Appendix I for a list of device I.D. s). 

The command byte contains a device dependent command (see Appendix I 
for a list of device commands). 

The auxilliary bytes contain more device dependent information. 

The checksum byte contains the arithmetic sum of the first four bytes 
(with the carr^ added back after every addition). 

COMMAND FRAME ACKNOWLEDGE 

The peripheral being addressed would normally respond to a command 
frame by sending an ACK byte ($41) to the computer; if there is a 
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problem with the command frame, the peripheral should not respond. 
DATA FRAME 

Following the command frame (and ACK) may be an optional data frame 
which is formatted as shown below: 



! i 
! ! 
! data ! 



! bytes ! 

i • 
i i 



{ checksum ! 



This data frame may originate at the computer or at the device 
controller/ depending upon the command. Current device controllers 
expect fixed length data frames as does the computer/ where the data 
frame length is a fixed function of the device type and command. 



The checksum value in the data frame is the arithmetic sum of all 
the frame data preceding the checksum/ with the carry from each 
addition being added back (the same as for the command frame). 



of 



In the case of the computer sending a 
peripheral is expected to send an ACK 
and send a NAK ($4E) or do nothing if 
See the first flowchart at the end of 



data frame to a peripheral/ the 
if the data frame is acceptable 
the data, frame is unacceptable, 
section 9. 



OPERATION COMPLETE 

A peripheral is also expected to send an operation COMPLETE byte ($43) 
at the time the commanded operation is complete. The location of this 
byte in the command sequence for each command type is shown in the 
timing diagrams which follow If the operation cannot go to 

normal/ error-free completion/ the peripheral should respond with an 
ERROR byte ($45) instead of COMPLETE. 



Bus timing 

This section provides timing diagrams for the three types of command 
sequences: data send, data receive and immediate. 

DATA SEND sequence: 
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■ 



COMMAND- 



I 
I 



+ 

I 



DATA OUT 



! cmnd ! 
+frame + 



+ // + 

! data ! 
// — + frame + 



+ — h 



DATA IN 



ACK 



+ — t- 
• i 



I ! 



+ + .// + +~ 

ACK CMPL 



i i 



to 



ti t 



t3 



t4 



t5 



DATA RECEIVE sequence: 



+ 



COMMAND- 



DATA OUT 



+ + 

! cmnd ! 
— i-frame + 



DATA IN 



+-+ 



+ + 
ACK 



— // — 



+ — H 

CMPL 



//- 

data 
frame 



+ 



to 



tl t2 



t5 
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IMMEDIATE sequence 



+ 



COMMAND- 



DATA OUT 



+ + 

i cmnd I 
+f rame + 



DATA IN 



• — H 



+ — h 



ACK 



CMPL 



! » 



{ i 



to 



ti t2 



tO is the delay between the lowering of COMMAND- and the transmission 
of the first byte of the command frame. The computer generates this 
delay. 



750 usee 



computer 1 0 ( m i n ) * 
computer tO (max) « 1600 usee. 



ti is the delay between the transmission of the last bit of the 
command frame and the raising of the COMMAND- line. This delay is 
generated by the computer. 

computer tl (min) = 650 usee, 
computer tl (max) = 950 usee. 



t2 is the delay between the raising of COMMAND- and the transmission 
of the ACK byte by the peripheral. The peripheral generates this 
delay. 

computer t2 (mm) == 0 usee, 
computer t 2 (max) = 16 msec. 
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t3 is the delay between the receipt of the last bit of the ACK byte 
and the transmission of the first bit of the data frame by the 
computer. The computer generates this delay. 

computer t3 (min) = 1000 usee, 
computer t3 (max) = 1800 usee. 



peripheral t3 (mm) - ?? 
peripheral t3 (max) = ?? 

t4 is the delay between the transmi 
frame and the receipt of the first 
computer. The peripheral generates 



ssi on of the last bit of the data 
bit of the ACK byte by the 
this delay. 



computer t4 (min) = 850 usee, 
computer t4 (max) = 16 msec. 

peripheral t4 (min) = ?? 
peripheral t4 (max; = ?? 

t5 is the delay between the the receipt of the last bit of the 
byte and the first bit of the COMPLETE byte by the computer. fhe 
peripheral generates this delay. 

computer t5 (min) = 250 usee. 

computer t5 (max) = 255 sec. (handler dependent) 

peripheral t5 (min) = ?? 
peripheral t5 (max) = N/A 



Handler environment 

Non-resident handlers may be installed in at least three different 
manners: 

1. As booted software from disk or cassette. 

2. Resident in a cartridge (A or B) 

3. Downloaded from a serial bus device. 

This section will discuss the basic mechanisms for handler 
installation for these environments. In order to fully utilize the 
information in this section, you must have read and understooo the 
foil owing sections: 

Program environments. . . section 3 
RAM region. . . section 4 
Memory dynamics. . . section 4 
System in i t ia 1 i z at i on ... sec t i on 7 

Adding new device handlers/peripherals. . section 9 
Program environment and initialization. . . section 10 
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9. 5. 1 Bootable handler 

The disk or cassette booted software will want to insert the handler's 
vector table pointer and name to the Device Table whenever the booted 
software's initialization entry point is entered (on power up and 
CS/RESETD ) . Remember that both power up and CS/RESET 3 clear the Device 
Table of all but the resident handler entries. 



Cartridge resident handler 

The cartridge software will want to insert the handler's vector table 
pointer and name to the Device Table whenever the cartridge's 
initialization entry point is entered (on power up and CS/RESET3). 
Remember that both power up and CS/RESET 3 clear the Device Table of 
all but the resident handler entries; therefore the device table, must 
be reestablished by the handler initialization code upon every entry. 



Fl oucharts 

The following pages contain process flowcharts showing the SIO and 
peripheral actions for the Serial bus command forms. 
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TIMEOUT 
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FRAME 



I 



GET N BYTES 
FROM BUS 



SEND ACK 



I 



ATTEMPT TO 
PERFORM 
INDICATED 
OPERATION 



SEND 

COMPLETE 




TIMEOUT 




SEND NAK 




SEND ERR 
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IMMEDIATE 
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SEND ERR 



SEND 

COMPLETE 
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10 Program environment and initialization 

This section discusses several of the different software environments 
that are possible using the OS Configurations other than those 
discussed here are possible* and a thorough understanding of the power 
up and CS/RESETD processes (as described in section 7) will be 
necessary to evaluate other alternatives. 



Car tr i d g e 

Most games (and some language processors) are supported via the 
cartridge environment. The cartridge resident software is in control 
of the system* sometimes using the OS and sometimes not. A cartridge 
can specify whether the disk is to be booted at power up time; whether 
the cartridge is to provide the controlling software/ or whether the 
cartridge is a special diagnostic cartridge. These options are 
specified by bits in the cartridge header/ as shown below: 
space 1; need 13 

B.A^iCt ) i start address \ \ 

+ + 

+ + ^ 

! option byte \ 
+ + 

^ . ! cartridge ! 

-i — h 

! init address ! BFFF (9FFF for cartridge B) 
+ + 



The byte of "00" is used to allow the OS to determine when a cartridge 
is inserted; locations BFFC and 9FFC will not read zero when there is 
neither RAM at those locations nor a cartridge inserted. RAM is 
differentiated from a cartridge by its ability to be altered. 




EEQ3 



The option byte has the following option bits: . 

Bit-0 = 0/ then do not boot the disk. 
I 1/ then boot the disk. 

Bit-2 = 0/ then init but do not start the cartridge. 

1/ then init and start the cartridge. 

Bit-7 = 0/ then cartridge is not a diagnostic cartridge. 

1/ then cartridge is a diagnostic cartridge &. control 
will be given to the cartridge before any of the OS 
is initialized <JMP < BFFE ) ) . 

The cartridge init address specifies the location to which the OS will 
JSR during all power up and CS/RESET3 operations. As a minimum/ this 
vector should point to an RTS instruction. 
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The cartridge start address specifies the location to which the OS 
will JMP during ail power up and C S/RESET 3 operations, if bit-1 of the 
option byte is = I. The application should examine the variable WARMST 
COOOS3 if C S/RESET 3 action is to be different than power up (WARMST 
will be zero on power up and non-zero thereafter). 



Cartridge without booted support package 

A cartridge which does not specify the disk boot option and does not 
support the cassette boot possibility may use lower memory (from 0480 
to the address in MEMTOP C02E53) in any way it sees fit. 

Cartridge with booted support package 

A cartridge which does specify the disk boot option or does support 
the cassette boot possibility must use some care in its use of lower 
memory. The following regions are defined: 

04S0-06FF is always available to the cartridge. 

MEM LQ/MEMTOP region is always available to the cartridge. 

Disk booted software 

Software may be booted from the disk at power up time in 
response to one of the following conditions: 

Neither Cartridge A nor E is inserted. 

Cartridge A is inserted and has bit-0 of its option byte 
CBFFD3 = 1. 

Cartridge B is inserted and has bit-0 of its option byte 
T9FFD3 = 1. 

If any of these conditions are met/ the OS will attempt to read the 
boot record from sector #1 of disk drive i and then transfer control 
to the software that was read in. The exact sequence of operations 
will be explained later in this section 

Disk boot file format 

The key region of a disk boot file is the first 6 bytes, which are 
formatted as shown below: 
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Z' 
<4 



+ + 



flags 
# of sectors 



+ + 

memory address 
+- -+ 

to start load 
+ + 



in i t 
address 



+ + 

boot 
continuation 
code 



1st byte 



6th byte 



The 1st byte is stored in DFLAOS [02403, but is otherwise unused. It 
should equal zero. 

The 2nd byte contains the number of 128 byte disk sectors to be read 
as part of the boot process (including the record containing this 
information). This number may range from 1 to 255/ with 0 meaning 256 

The 3rd and 4th bytes contain the address (lo/hi) at which to start 
loading the first byte of the file. 

The 5th and 6th bytes contain the address (lo,hi) to which the booter 
will transfer control after the boot process is complete and whenever 
the CS/RESET3 key is pressed. 

The Disk File Management System (FMS) has extra bytes assigned to its 
boot record/ but this is a special case of the generalized disk boot 
and is discussed in section 5 



Disk boot process 

The disk boot process is described step by step for a configuration in 
which no cartridge is installed. For the general case see section 7. 

1. Read the first disk record to the cassette buffer £04001. 

2. Extract information from the first 6 bytes: 

Save the flags byte to DFLAGS C0240, ID. 

Save the # of sectors to boot to DBSECT [0241/ ID. 

Save the load address to BOOTAD [0242,23. 

Save the initialization address in DOSINI C000C2D. 

3. Move the record just read to the load address specified 

4. Read the remaining records directly to the load area. 
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5. JSR to the load address+6 where a multi-stage boot process may 
continue; the carry bit will indicate the success of this 
operation (carry set = error/ carry reset = success). 

6. JSR indirectly through DOS INI for initialization of the 
application; the application will initialize and return. 

7. JMP indirectly through DOSVEC to transfer control to the 
app 1 i cat ion. 

Pressing the CS/RESET3 key after the application is fully booted will 
cause steps 6 Se 7 to be repeated. 

Regarding step 5 — After the initial boot process is complete/ the 
booter will transfer control to the 7th byte of the first record; at 
this point the software should continue the boot process/ if it is a 
multi-stage boot. The value of MEMLO C02E73/ which should point to the 
first free RAM location beyond the software just booted/ should be 
established by the booted software as shown below: 

LDA #END+1 i SETUP LSB. 

STA MEMLO 
STA APPMHI 

LDA #END+ 1/256 ; SETUP MSB. 

STA MEMLO+1 
STA APPMHI+1 

If the booted software is to take control of the system at the end of 
the boot operation/ the vector DOSVEC COOOA3 must be setup by the 
application at this time; DOSVEC points to the restart entry for the 
booted application. If the booted software is not to take control/ 
then DOSVEC should remain unchanged. 

LDA #RESTRT ; RESTART LSB. 

STA DOSVEC 

LDA #RESTRT/256 

STA DOSVEC+ i 

Regarding step 6 — The initialization point is entered on every 
HS/RESETl and power up; internal initialization may take place here. 
For controlling applications initialization may also be deferred until 
step 7. 



Sample disk bootable program listing 

Shown below is a skeletal program which can be booted from the disk 
and which retains control when it is entered. 

; THIS IS THE START OF THE PROGRAM FILE. 

PST= *0700 i (OR SOME OTHER LOCATION). 

♦ « PST ; (. ORG). 
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THIS IS THE DISK BOOT CONTROL INFORMATION. 



. BYTE 0 

.BYTE PND-PST+127/128 

. WORD PST 

.WORD PINIT 



NUMBER OF RECORDS. 

MEMORY ADDRESS TO START LOAD. 

PROGRAM INIT. 



i THIS IS THE START OF THE BOOT CONTINUATION. 



LDA 
STA 
STA 
LDA 
STA 
STA 



#PND 

MEMLO 

APPMHI 

#PND/256 

MEMLO+1 

APPMHI+1 



ESTABLISH LOW MEMORY LIMITS. 



LDA 
STA 
LDA 
STA 



#RESTRT 
DOSVEC 
#RESTRT/256 
DOSVEC+1 



ESTABLISH RESTART VECTOR. 



CLC 



SET FLAG FOR SUCCESSFUL BOOT. 



RTS 

i APPLICATION INITIALIZATION ENTRY POINT. 

PINIT RTS ; NOTHING TO DO HERE FOR . . . 

; ... CONTROLLING APPLICATION. 

; THE MAIN BODY OF THE PROGRAM FOLLOWS. 
RESTRT=* 

; THE MAIN BODY OF THE PROGRAM ENDS HERE. 

PND= * ; 'PND ' = NEXT FREE LOCATION. 



Program and procedure to create disk boot files 

This section provides a procedure that may be used to make bootable 
files on disks. The procedure given is not the only one possible, and 
no claims are made as to its elegeance. The dialogue shou/n assumes 
that one is logged onto the PDP-11/34 computer from one of the 
development systems in the laboratories and is using LNBUG 2.0. An 
ATARI 400 or an ATARI 800 Personal Computer System with a disk drive 
is required. 

User: OSL <cr> 

Comp: loads the operating system. 
User: DLOAD BOOTDY <cr> 



. END 
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Comp: loads the boot file maker. 



User: <CTRL-P> 



go to LNBUG control 



X <cr> 



LNBG: responds with LNBUG prompt. 

User: put a formatted disk in the drive. 



User: E477G <cr> 



starts OS and initializes mem 



LNBG: responds with LNBUG prompt in response to BRK in 'BOOTDY'. 



User: R 



User: $ <cr> <cr> 



Comp: . 

User: DLOAD xxxxx <cr> 



Y 



erify BRK address 



returns to PDP-11/34 control. 
PDP-11 prompt, 
xxxxx = name of application file 



Comp: loads the application file. 



User : <CTRL~P: 
X < c r > 



go to LNBUG control 



LNBG: responds with LNBUG prompt 



User : B001G<cr> 



resume 'BOOTDY ' 



User: wait for completion of the disk file write. 

LNBG responds with LNBUG prompt in response to BRK in 'BOOTDY ' 



User: R 



verify BRK address 



User; to write another boot file, type BOOIG <cr>. 



Shown below is a listing of the program referred to as 'BOOTDY' 
procedure above: 

; THIS PROGRAM WRITES A SINGLE "FILE" TO THE DISK AND IS 
USED IN CONJUNCTION WITH A PROCEDURE TO MAKE DISK 
BOOTABLE F I LES THE FOLLOWING TWO SYMBOLS MUST EE EQUATED 
USING THE MEMORY LIMITS OF THE PROGRAM TO BE COPIED: 

'PST' - PROGRAM START ADDRESS ( SEE SAMPLE PROGRAM). 
'PND' = PROGRAM END ADDRESS (SEE SAMPLE PROGRAM). 



in the 



S E C S I Z 
PST^ 

PND= 
FLEN= 



12G 

$0700 

$1324 

PND-PST+SECSIZ 



DISK SECTOR SIZE 



-1/SECSIZ i # OF SECTORS IN FILE 
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*BOOO 



i THIS PROGRAM'S ORIGIN 



BOOTB BRK 



; *** LOAD APPLICATION *** 



fUP DEVICE CONTROL BLOCK FOR DISK HANDLER CALL 



LDA 
STA 



#FLEN 
COUNT 



# OF SECTORS TO WRITE 



LDA 
STA 



#1 

DUN I T 



DISK DRIVE #1 



LDA 
STA 



# 'W 

DCOIiND 



; SETUP FOR WRITE WITH CHECK 



LDA 
STA 
LDA 
STA 



#PST 
DBUFLO 
#PST/256 
DBUFHI 



POINT TO START OF APPLIC. PROG 



LDA 
STA 
LDA 
STA 



#01 
DAUX1 
#00 
DAUX2 



; SETUP STARTING SECTOR # = 0001 



i NOW WRITE THE FILE ONE SECTOR AT A TIME 



B0T010 OSR 
BMI 



DSK I NV 
DERR 



WRITE ONE SECTOR 
ERROR. 



LDA 
CLC 
ADC 
STA 
LDA 
ADC 
STA 



DBUFLO 

#SECSIZ 
DBUFLO 
DBUFHI 
#0 

DBUFHI 



INCREMENT MEMORY ADDRESS 



INC 
BNE 
INC 



DAUX1 

B0T020 

DAUX2 



INCREMENT SECTOR # 



B0T020 DEC 
BNE 



COUNT 
B0T010 



; MORE SECTORS TO WRITE? 
; YES. 



BRK 



; STOP WHEN DONE 



DERR 



BRK 



; STOP ON ERROR 



COUNT #=#+1 



; SECTOR COUNT. 



; THIS IS THE CARTRIDGE HEADER 



*BFF9 



; "A" CARTRIDGE 
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INIT RTS 

. WORD BOOTE 
. BYTE C, 4 
.WORD INIT 

. END 



Cassette booted software 

Software may be booted from the cassette at power up time in much the 
same way as from the disk/ as described in the previous section. The 
following requirements must be met in order to boot from the cassette: 

The operator must be pressing the START key as power is applied 

to the system. 

A cassette tape with a proper boot format file must be installed 
in the cassette drive, and the PLAY button must be pressed. . 

When the operator is given the audio prompt by the cassette 
handler he must press the CRETURND key. 

If all of these conditions are met, the OS will read the boot file 
from the cassette and then transfer control to the software that was 
read in. The exact sequence of operations will be explained later in 

this section. 

Cassette boot file format 

The key region of a cassette boot file is the first 6 bytes, which are 
formatted as shown below: 



! # of records 
+ 

i memory address 
+- -+ 
! to start load 



+- 



in i t 
address 



— H 



+ 



1st byte 



6th byte 



The 1st byte is not used by the cassette boot process. 

The 2nd byte contains the number of 128 byte cassette records to 
be read as part of the boot process (including the record 
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containing this information). This number may range from 1 to 
255; u/ith 0 meaning 256. 

The 3rd and 4th bytes contain the address (lo,hi> at which to start 
loading the first byte of the file. 

The 5th and 6th bytes contain the address do, hi) to which the booter 
will transfer control after the boot process is complete and whenever 
the ES/RESETH key is pressed. 



Cassette boot process 

The cassette boot process is described step by step for a 

configuration in which no cartridge is installed and no disks are 

attached. For the general case see Section 7. 

1. Read the first cassette record to the cassette buffer. 

2. Extract information from the first 6 bytes: 

Save the # of records to boot. 

Save the load address. 

Save the initialization address in CASINI C0002D. 

3. Move the record just read to the load address specified. 

4. Read the remaining records directly to the load area. 

5. JSR to the load address+6 where a multi-stage boot process may 
continue; the carry bit will indicate the success of this 
operation (carry set = error, carry reset = success). 

6. JSR indirectly through CASINI for initialization of the 
application; the application will initialize and return. 

7. JMP indirectly through DOSVEC to transfer control to the 
application. 

Pressing the CS/RESETD key after the application is fully booted will 
cause steps 6 & 7 to be repeated. 

Regarding step 5 — After the initial boot process is complete, the 
booter will transfer control to the 7th byte of the first record; at 
this point the software should continue the boot process (if it is a 
multi-stage boot) and then stop the cassette drive, which due to a 
system bug will still be running, using the following instruction 
sequence : 

LDA #*3C 

STA PACTL CD3023 

The application should then set a value in MEMLO C02E7D which points 
to the first free RAM location beyond the software just booted, as 
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shown below: 



LDA 


#END+i 


; SETUP 


STA 


MEMLO 




STA 


APPMHI 




LDA 


#END+ 1/256 


i SETUP 


STA 


MEMLO+i 




STA 


APPMHI+1 





If the booted software is to take control of the system at the end of 
the boot operation, the vector DDSVEC lOOOA3 must be setup by the 
application at this time; DOSVEC points to the restart entry for the 
booted application. If the booted software is not to take control/ 
then DDSVEC should remain unchanged. 



LDA #RESTRT ; RESTART LSE. 

STA DOSVEC 

LDA #RESTRT/256 

STA DOSVEC+1 



Regarding step 6 — The initialization point is entered on every 

CS/RESETJ and power up; internal initialization may take place here. 

For controlling applications initialization may also be deferred until 
step 7. 



Sample cassette bootable program listing 

Shown below is a skeletal program which can be booted from the 
cassette and which retains control when it is entered. 

; THIS IS THE START OF THE PROGRAM FILE. 



PST- 



$0700 
PST 



(OR SOME OTHER LOCATION ) . 

( . ORG ) . 



; THIS IS THE CASSETTE BOOT CONTROL INFORMATION 



BYTE 0 

BYTE PND-PST+127/128 

WORD PST 

WORD PINIT 



(DOESN'T MATTER). 

NUMBER OF RECORDS. 

MEMORY ADDRESS TO START LOAD 

PROGRAM INIT. 



; THIS IS THE START OF THE BOOT CONTINUATION 



LDA 

STA 



#*3C 
PACTL 



STOP THE CASSETTE 



LDA 
STA 
STA 
LDA 



#PND 
MEMLO 
APPMHI 
#PND/256 



i ESTABLISH LOW MEMORY LIMITS 
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CTA 




STA 


APPMHI+i 


J HA 




OTA 

b 1 A 


DUSvtC 


LDA 


#RESTRT/256 


STA 


DOSVEC+1 


CLC 




RTS 





i ESTABLISH RESTART VECTOR. 



SET FLAG FOR SUCCESSFUL BOOT 



; APPLICATION INITIALIZATION ENTRY POINT. 
PINIT RTS i 



NOTHING "TO DO HERE FOR . . . 
. . . CONTROLLING APPLICATION 



i THE MAIN BODY OF THE PROGRAM FOLLOWS. 
RE3TRT=* 

; THE MAIN BODY OF THE PROGRAM ENDS HERE. 

PND= * i 'PHD ' « NEXT FREE LOCATION 

. END 



Program and procedure to create cassette boot files 

This section provides a procedure and a program listing that may be 
used to make bootable files on cassette tapes. The procedure given is 
not the only one possible, and no claims are made as to its elegeance. 
The dialogue shown assumes that one is logged onto the PDP-11/34 
computer from one of the development systems in the laboratories and 
is using LNBUO 2.0. An ATARI 400 or ATARI SCO Personal Computer System 
with an ATARI 410 Program Recorder is also required. 



User: OSL <cr 

Comp: loads the operating system. 

User: DLOAD BOOTCY <cr> 

Comp: loads the boot file maker. 

User: <CTRL-P> go to LNBUG control. 

X <cr> 

LNBG: responds with LNBUG prompt. 

User: E477G <cr> starts OS and initializes mem. 

User: wait for tone indicating cassette write request. 

User: <CTRL-C> interrupts the initialized prog 
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LNBG: responds with LNBUG prompt. 

User: % <cr> <cr> returns to PDP-li/34 control. 

Comp: . PDP-11 prompt. 

User: DLOAD xxxxx <cr> xxxxx = name of application file. 

Comp: loads the application file. 

User: <CTRL-P> go to LNBUG control. 

X <cr> 

LNBG: responds with LNBUG prompt. 

User: P resume 'BOOTCY'. 

User: setup cassette drive to record on tape. 

User: press the CRETURND key on the Model 400/800 keyboard. 

User: wait for completion of the cassette file write. 

LNBG: responds with LNBUG prompt in response to BRK in 'BOOTCY'. 

User: R verify BRK address. 

User: to write another boot file, type BOOOG <cr>. 

Shown below is a listing of the program referred to as 'BOOTCY' in the 
procedure above: 

; THIS PROGRAM WRITES A SINGLE FILE TO THE CASSETTE AND IS 
; USED IN CONJUNCTION WITH A PROCEDURE TO MAKE CASSETTE 
; BOOTABLE FILES. THE FOLLOWING TWO SYMBOLS MUST BE EQUATED 
; USING THE MEMORY LIMITS OF THE PROGRAM TO BE COPIED: 

i 'PST' = PROGRAM START ADDRESS (SEE SAMPLE PROGRAM). 

; 'PND ' = PROGRAM END ADDRESS (SEE SAMPLE PROGRAM). 

PST= *0700 
PND= $1324 

FLEN= PND-PST+127/ 128*128 ; ROUND UP TO MULTIPLE OF 128. 
*= *B000 ; THIS PROGRAM'S ORIGIN. 

BOOTS LDX #$10 ; USE IOCS #1. 

; FIRST OPEN THE CASSETTE FILE FOR WRITING. 

LDA #OPEN i SETUP FOR DEVICE "OPEN" . 

STA ICCOM, X 

tf 
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LDA 


#OPNOT 


• 


DIPECTIOlM IS "OUTPUT" 


STA 


ICAX1, X 






LDA 


#*eo 


• 

/ 


SELECT SHORT IPG. 


CT A 

STA 


ICAX2/ X 






LDA 


#CFILE 


i 


SFTUP PDIMTFR Tfl HFU TfP 


STA 


ICBAL, X 






LDA 


#CFILE/256 






STA 


ICBAH, X 






JSR 


CIOV 




ATTEMPT TO OPEN FILE. 


BMI 


CERR 


« 


ERROR. 



; NOW WRITE THE ENTIRE FILE A3 ONE OPERATION. 



LDA 
STA 

LDA 
STA 
LDA 
STA 

LDA 
STA 
LDA 
STA 

JSR 
BMI 



#PUTCHR 
ICCOM, X 

#PST 
ICBAL, X 
#PST/256 
ICBAH, X 

#FLEN 
ICBLL, X 
#FLEN/256 
ICBLH, X 

CIOV 
CERR 



; SETUP FOR "PUT CHARACTERS". 



; POINT TO START OF APPLIC. PROG 



; SETUP # OF BYTES TO WRITE. 



WRITE ENTIRE FILE 
ERROR. 



i NOW CLOSE THE FILE AFTER SUCCESSFUL WRITE 



CERR 



LDA 
STA 

JSR 
BMI 

BRK 
BRK 



#CLOSE 
ICCOM, X 

CIOV 
CERR 



; SETUP FOR "CLOSE 



il 



CFILE . BYTE "C: ". CR 
; THIS IS THE CARTRIDGE HEADER 
♦= *BFF9 
INIT 



; CLOSE THE FILE 

; ERROR. 

; STOP WHEN DONE 

} STOP ON ERROR. 

; FILE NAME. 



'A" CARTRIDGE 



RTS 
. WORD 
. BYTE 
. WORD 



BOOTB 
0, 4 
INIT 
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END 
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11. Advanced techniques and application notes 

This section presents information which may be of use to the 
user who wishes to use the capabilities of the OS and use some 
of the hardware capabilites that aren't directly available 
through the OS and# in fact, may be in direct conflict with 
parts of the OS. 



Sound generation 

The OS uses the POKEY sound generation capabilities only in the I/O 
subsystem, for cassette FSK tone generation and for the "noisy bus 11 
option in SIO. 



Capabilities 

The hardware provides 4 independently programmable audio channels 
which are mixed and sent to the television set as part of the 
composite video signal. The POKEY registers shown below are all 
concerned with sound control (as described in the ATARI Personal 
Computer System HARDWARE MANUAL). 



AUDCTL CD20S3 
AUDC1 CD2013 & AUDF1 
AUDC2 CD2033 & AUDF2 
AUDC3 CD2053 & AUDF3 
AUDC4 CD207 3 & AUDF4 



CD200D 
CD202D 
CD204D 
CD206 3 



Audio control. 
Channel 1 control 
Channel 2 control 
Channel 3 control 
Channel 4 control 



Conflicts with OS 

There are two potential conflicts with the OS involving sound 
generation: 

The OS may generate its own sounds and then turn off all sounds as 
part of I/O operations to the cassette and the serial bus 
peripherals. 

The OS does not turn off sounds on CS/RESET3 or C BREAK 3 ; if the 
sounds are to be turned off under those conditions, the 
controlling program must provide that capability. 



Screen graphics 
Hardware capabilities 

The hardware capabilities for screen presentations are quite 
versatile; the OS uses a very small amount of the capability provided. 
The means of extension, however, are non-trivial; and making changes 
to a screen format while still utilizing the resident Display handier 
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will be difficult. See the ATARI Personal Computer System HARDWARE 
MANUAL for information regarding screen presentations. 



OS capabilities 

The resident Display handler arbitrarily supports 8 of the 11 possible 
full screen modes (11 of 14 modes if the QTIA chip is used in place of 
the CTIA), and allows for an optional "split screen" text window of 
fixed size. The hardware allows for many more options than the Display 
handler supports, as will be seen by reading the ATARI Personal 
Computer System HARDWARE MANUAL. 



Cursor control 

The Display handler text and graphics cursors may be directly 
controlled by the user as described in section 5 and in Appendix K. 

Bl-4. 



Color control 



The color register assignments that the Display handler makes upon 
OPEN commands may be altered by the user as described in Appendix K 

and elsewhere. Note that every CS/RESET3 or Display handler OPEN 
will reset the values back to the system default. 



11 



Alternate Character Sets 



In screen text modes 1 and 2/ two character sets are available, 
the sets being selectable by the value stored in database variable 
CHBAS C02F43/ tthe default value of $EO provides capital (upper 
case) letters/ numbers and the punctuation characters ) c or r esp ond ing 
to display codes $20 through $5F in Appendix E); the alternate 
value of $E2 provides lower case letters and the special character 
graphics set (corresponding to display codes $60 through $7F and 
$00 through $1F in appendix E). 



In addition, user defined character sets may be obtained for text 
modes 0/ 1 and 2 by provided the character matrix definitions in 
RAM and setting CHBAS to point to those definitions. CHBAS always 
contains the most significant bits of the memory address of the 
start of the character definitions, as shown below: 



CHBAS 



+ - + — + — K — "f — I h — h 



Test mode 0 



—+-+-+--+ — h-+-+- 



— I---*- — j- — »--+ 
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Where X indicates an ignored address bit (assumed - 0). 



Each character 



is defined by an 8 x 8 bit matrix; the character 
' is defined as shown below: 



7 0 Byte 

0 
1 
2 
3 
4 
5 
6 
7 

The storage for the character set involves 8 consecutive bytes 
for each character with characters ordered consecutively by their 
internal code value (see the discussion in appendix K relating 
to B55). 

Character base Character for 

CodeSOO 8 bytes 



Character for 
Code $0/ increasing addresses 



Character for 
Code *7E 

Character for 
Code *7F 



Play ers/missi les 

The OS makes no use of the player/missile generation capability of the 
hardware; but, luckily, it may be used independently of the OS with no 
conflict. 

Hardware capabilities 

The hardware allows a number of independently moveable screen objects 
(of limited width) to be positioned and moved about the screen without 
affecting the M p lay field" (bit mapped graphics or character) data. 
Priority control allows the various objects to have a display 
precedence in case of conflict (overlap). 
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Conflicts with OS 

The only potential problem is that the user must assure that the 
player/missile data is address aligned as required by PMBASE CD4073, 
and finding a suitable free area that is guaranteed to be free under 
all environments could be a problem 



Reading game controllers 

The game controllers shown below are read by the OS as part of the 
stage 2 VBLANK process (see Appendix K Jl-9): 

Joysticks/triggers 1-4. 
Paddle c on tr o 1 1 er s / tr i g g er s 1-8. 
Driving controllers/triggers 1-4. 
Lightpen/ trigger 
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In addition to these controllers, other information may. be sensed 
sent using the PIA chip to which the console connectors are 
in ter f ac ed . 



or 



Keyboard controller sensing 

The PASCAL procedure below shows how to read data from an ATARI 
keyboard controller' which is connected to the first port, the hardware 
register and OS database names used 
are from the OS equate file. 

FUNCTION READKEY ( DR I VEVAL: BYTE ) : BYTE; 
BEGIN 

PORTA : ~ DR I VEVAL < set row select >; 



DELAY 

KCODE : = 0 
IF PADDLx > 
IF PADDLx > 
IF STRIGx = 
READKEY : = KCODE 
END; 



< wait for OS to read data >; 
■C preset for no key read >; 



10 THEN KCODE 
10 THEN KCODE 
0 THEN KCODE 

{ set 



= 1 



s 



■ 2 



c o l umn l 
{. column 2 
: = 3 < col umn 3 
function value 



>i 

>i 
■% 



BEGIN 



( setup PIA port A for 4 bits out ); 1 10010/ 10025set up PIA 
port A for 8 bits out > 



PACTL 
PORTA 
PACTL 



— tor, 



< direction register select >; 



= $FF -r se t direction bits for output >; 

= $34 -C data register select >; 



{ setup of driving values, each selects a different row > 



DVALCOj 
DVALl 1 3 
DVALC23 
DVALC33 



- *EE; 

= $DD; 
AD O • 

— +r L> t-> I 

= $77; 



REPEAT -C loop to read the controller keys > 



I : - 0; 
REPEAT 



KEY READKEY (DVALC I 1 ) < read a row >; 
IF KEY <:> 0 THEN KEY :■ KEY + (1*3) < encode }; 
I . = I + 1 -C next row > 

UNTIL (I > 3) OR (KEY O 0); 

IF KEY O 0 THEN WRITELN ('KEY VALUE = ' , KEY ) 
UNTIL FALSE < forever! > 

END. 

The table below shows the variable/register values used for reading 
keyboard controller from each of the four controller ports 

Port 1 Port 2 Port 3 Port 4 
+_+_+_+_+_+-+-+-+- +-+-+-+-+-+-+--■*--+ -+ ~~ r - + ~ +-+ — *■ 

1 J 
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FBi F7 



I FE, FD, FE, 
! F7 



roiii s e 1 1 
ect i 

I 1 i- — -f — + - + — — + — + + h — f-- + - + --f-4- 

Port B ! 
row se- ! 
lect ! 

+ - -f- — i » J i i h — 4 - + - + - + - + - + — h- +- 

Column 1! PADDL 1 i PADDL 31PADDL 5 
Sense ! i ! 

4-4-4-4-~ + -4- + -4 — t I I i * « »- — h-4-4- 

Coiumn 2 I PADDL 0! PADDL 2 ! PADDL 4 



Port A ! OF I FO 
direction! 
bits I 

+ -4-4-4-4-4-4-4-^-4-4 h - 4- 4 - 4 - 4 - 4 - 4 

Port B 
direction 
bits 

4-4-4 — h — h — H — 4 — I i i — 4 — 4 — h-4-4-4-4-4 

Port A I FEi FDi 



— H-4-4-4-4-4 



OF 



f FO ! 



-4-4-4-4-4-4 



EF.. DF ! 

BFi 7F I 



4-4—4-4-4—4 

! REF/ DF.. I 



BF/ 7F 



4-4-4-4 — h-4 

I PADDL 7 I 



4-4-4-4-4-4 

i PADDL 6 ! 



Sense 



4-4-4-4-4 — + .-4-4-4-4-4 — 4-4-4 — h- 4 — 4- 

Column 3JSTRIG OISTRIG 1ISTRIG 2 
Sense ! I ! 

4-4 — h — 1 — 4 4- 4 — 4 -4- 4 — r — H-4 -4 — h— 4 -4- 



4-4-4-4-4-4 

iSTRIG 3 I 



4-4-4-4-4-4 



Front panel connectors as I/O ports 

7he three pages that follow show how some of the pins in the front 
panel (game controller) connectors can be used as general I/O pins. 

. 00 

ATARI 400/800 Front Panel (Controller; Jack as I/O Ports 

Har d war e Information: 
PIA (6520 / 6820) 

Out: TTL levels, 1 load 

In TTL levels- 1 load For more information refer 

to 6520 chip manual. 



Port A Circuit (typical): 



652£) 



(A) 
Port 



220 



Port B Circuit (typical): 

+5 



6520 



(B) 
Port 



4.7K 

220 -L .001 



Jack 



V ••••••• 7 



Jack 



Male connector, FRONT view 

Pin 8= Ground 

Pin 7= Vcc (+5v *) 

* Note: 50ma maximum 
total external drain 
on power supply allowed 
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"Trigger" Port Circuit (typical): 



CTIA Trig 



220 



.001 



Jack 



Software Information : 

6520 PIA: (this also pertains to all of the following: **) 
Port A control (address $ D302) 



7 6 5 4 3 2 10 
10101H1U1X]TO 




Write this into this register 
ort A Data/Data direction addressing control 
0= Address data direction at $ D300 
1= Address data at $ D300 



Port A data direction (address $ D300) 
76543210 

Write this into this register 
Data direction control for Port A 



XXXXXXXX 



1= Out 
0= In 



Port A data (address $ D300) 

7 6 5 4 3 2 1 (* 
I 1 | I 1 1 1 I J Read or Write this register 

Jack 2 Jack 1 
Pin Numbers 



Port B control (address $ D303) 
10101111111X1010 I 
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6520 PIA: 

Port B control (address $ D302) 

7 6 5 4 3 2 1 0 

lg|0|l[l|llx|0|0{ Write this into this register 

Port B Data/Data direction addressing control 
0= Address data direction 
1= Address data 



Port B data direction (address $ D300) 

76543210 
|XlX|X|X|XlX|X|X | Write this into this register 

A ^ ^\ ft ft < fi ft /f\ 

Data direction control for Port B 

1= Out 
0= In 



Port B data (address $ D301) 
76543210 



4 3 2 1 4 3 2 1 

Jack #4 Jack #3 
Pin Numbers 



Four "trigger" ports: 
7 6 5 4 3 2 1 0 



0 


0 


0 


0 


0 


0 


0 


x| 



($ D010, $ D011, $ D012, $ D013) 
Read this port 



-Trigger value 

$ D010 = Port 1 pin 6 

$ D013 = Port 4 pin 6 



Other miscellaneous Software information: 

1) . The 0. S sets up all PIA ports as inputs during initialization 

2) . The 0. S. usually reads the above once per TV frame (during 

vertical blank) into RAM as follows: 



Database name 
STICKO 



STICK1 
STICK2 
STICK3 
STRIGO 



STRIG1 
STR I G2 
STRIG3 



PADDL1 



PADDL3 
PADDL5 
PADDL7 
PADDLO 
PADDL2 
PADDL4 
PADDL 6 



Address 
0278 



Data 



0729 
027A 
027B 
0284 



0285 
0286 
0287 



0272 
0274 
0276 
0271 
0273 
0275 
0277 



7 6 5 4 3 2 1 0 
|0|0|0|0|X|X1X1X 



Pins S 
Jack 1, pins 4, 3, 2, 1 



Jac k2, Pins 4, 3, 2, 1 
Jac k 3. Pins 4, 3. 2, 1 
Jac k 4. Pins 4, 3, 2, 1 
Jack 1, Pin 6 



1 



0270 


7 


6 


5 


4 


3 


2 


1 


0 




X 


X 


X 


X 


X 


X 


X 





[Jack 


2, 


Pin 


6 


Jack 


3, 


Pin 


6 


Jac k 


4, 


Pin 


6 


Jac k 


1, 


Pin 


5 


Jac k 


2, 


Pin 


5 


Jac k 


3, 


Pin 


5 


Jac k 


4, 


Pin 


5 


Jac k 


1, 


Pin 


9 


Jac k 


2, 


Pin 


9 


Jac k 


3, 


Pin 


9 


Jac k 


4, 


Pin 


9 



* Pins 5 and 9 are read through the paddle controller circuitry 

a nominal value of 7 indicates that the pin is high (or floating) 
and a nominal value of 228 indicates that the pin is pulled low. 



\ 
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Appendix A — CIO COMMAND BYTE values 



The following hex values are known to be legitimate CIO command 

Most handlers: 

03 — OPEN 

05 — GET RECORD 

07 — GET CHARACTERS 

09 — PUT RECORD 

OB — PUT CHARACTERS 

OC — CLOSE 

OD — GET STATUS 

Display handler only: 

11 — FILL 

12 — DRAW 

Disk File Manager only: 

RENAME 
DELETE 
FORMAT 
LOCK 
UNLOCK 
POINT 
NOTE 



20 — 

21 — 
22 

23 — 

24 — 

25 — 

26 — 
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Appendix B — CIO STATUS BYTE values. 



Shown below are the known CIO STATUS BYTE values. 



01 


(001 ) 





OPERATION COMPLETE (NO ERRORS) 


80 


( 128) 





CBREAK3 KEY ABORT 


81 


( 129) 





IOCB ALREADY IN USE (OPEN) 


82 


( 130) 




NON-EXISTENT DEVICE 


83 


( 131 ) 




OPENED FOR WRITE ONLY- 


84 


(132; 




INVALID COMMAND 


85 


( 133) 




DEVICE OR FILE NOT OPEN 


86 


( 134) 




INVALID IOCB NUMBER (Y reg only) 


87 


( 135) 


mm. 


OPENED FOR READ ONLY 


88 


(136) 





END OF FILE 


89 


( 137) 





TRUNCATED RECORD 


8A 


( 138) 




DEVICE TIMEOUT (DOESN T RESPOND.' 


8B 

^mw m** 


(139) 




DEVICE NAK 


8C 


(140) 




SERIAL EUS INPUT FRAMING ERROR 


8D 


( 141 ) 





CURSOR OUT OF RANGE 


8E 


( 142 ) 

N mm > Imp* * 




SERIAL BUS DATA FRAME OVERRUN ERROR 


8F 


(143) 




SERIAL BUS DATA FRAME CHECKSUM ERROR 

\mmT nfl • ■ mm ■ * mmmm mmmm wmw mm* 


90 


( 144 ) 




DEVICE DONE ERROR 


91 


( 145 ) 

^ mm ■ ^mf * 




BAD SCREEN MODE 


92 

• MM* 


( 146 ) 


__ 


FUNCTION NOT SUPPORTED BY HANDLER 


93 


( 147 ) 


_ 


INSUFFICIENT MEMORY FOR SCREEN MODE 


AO 


(160) 





DISK DRIVE # ERROR 


Al 


( 161 ) 





TOO MANY OPEN DISK FILES 


A2 


( 162) 




DISK FULL 


A3 


( 163) 




FATAL DISK I/O ERROR 


A4 


( 164) 




INTERNAL FILE # MISMATCH 


A5 


( 165) 




FILE NAME ERROR 


A6 


( 166) 




POINT DATA LENGTH ERROR 


A7 


( 167) 




FILE LOCKED 


A8 


( 1 68 ) 




COMMAND INVALID FOR DISK 


A9 


(169) 




DIRECTORY FULL (64 FILES) 


AA 


( 170) 




FILE NOT FOUND 


AB 


( 171 ) 




POINT INVALID 
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Appendix C — SIO STATUS BYTE values. 



Shown below are the known SIO STATUS BYTE values. 

01 (001) — OPERATION COMPLETE (NO ERRORS) 

8A (138) — DEVICE TIMEOUT (DOESN'T RESPOND) 

8B (139) — DEVICE NAK 

8C (140) — SERIAL BUS INPUT FRAMING ERROR 

8E (142) — SERIAL BUS DATA FRAME OVERRUN ERROR 

8F (143) — SERIAL BUS DATA FRAME CHECKSUM ERROR 

90 (144) — DEVICE DONE ERROR 
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Appendix E — Display codes (ATASCII) 



2X 



MX. 



6* 



Sx 



ftx 



cx 



♦ I 

4sT 

41 
4 A 




I* 
I I 

I 2 

13 

fir 

n 
is 

II 

IC 

IP 
te 

if 



3 





5 




6 
I 

il 
I 

( 
* 



/ 



* 
i 

2 

7 
8 

9 



> 

9 



A 

c 

t> 

e 

F 
Gr 

H 

X 

L 
H 

O 



P 



\/ 

Y 

c 
\ 



a. 
b 

c 
e 

9 
la 

* 

J 
I 

M 
V» 
0 



P 

3. 
r 
s 
t 
u 

V 
X 

A 

I 



<M V Co DCS tf<f -~lF. 
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Appendix F — Keyboard codes (ATAsCII) 



00 


t 


c'O 


< s p a c e > 


40 


<£ 


01 


A 


21 


i 


4 1 


A 

A 


Oc! 


r-, 

B 


22 


ii 




rj 


03 


C 


c: J 


44 
+f 


4o 


L 


04 


D 


24 




44 


n 
U 


05 


• — 
E 


2 a 




a 

4 D 


c 

b. 


06 


F 


26 




46 


f— 
r 


07 




27 


• 


47 


G 


OS 


H 


28 


( 


48 


i » 
H 


09 


I 


29 


) 


49 


I 


OA 


i 


2A 


# 


*+A 


J 


OB 


K 


2B 


-f 


4B 


K 


OC 


L 


2C 






• 

L 


OD 


M 


2D 




4D 


M 


OE 


N 


2E 


• 


/i r*~ 

4E 




OF 


D 


2F 


/ 


4F 


□ 


10 


P 


30 


0 


50 


F 


1 1 


Q 


31 


1 


51 


Q 


12 


R 




2 


52 


R 


13 




33 


3 


53 


S 


14 


T 


34 


4 


54 


T 


15 


U 


35 


5 


55 


0 


16 


V 


36 


* 

6 


5 to 




1 7 


1 1 

w 


3 / 


— T 

/ 


r- — t 

57 


w 


18 


X 


38 


8 


58 


X 


1 o 

x ? 


Y 


39 


9 


59 


Y 


1A 


2 


3A 




5A 


z 


IB 


< 9 S C > 


3B 




5B 


c 


■j r 


c u p y 


3C 




5C 


\ 


ID 


Cd own 


>3D 




5D 


3 


IE 


Cleft 


>3E 


> 


5E 




IF 


•Cr i g h t 


>3F 


- 


5F 





ou 


i 




to 1 


B 


OT3 /t»of iirn""^ C . .•••.'"3 


Oc 


h 

D 


Of c Hoi "> 




c 


7L/ a v 1 ! 1 5 c 1 v -• 




A 
G 








7r 5 ••. i/aU - y 


A A 


T 


nv rl / i \ / 


O / 


s 


r V c 


A P 


n 


C cr A - ."Hoi 


AQ 
O 7 


l 


cr cr •••• n c or f % 


6A 


J 




oE 


k 




6l 


1 






m 






n 


■ 


/ r- 

or 


0 




"7 r\ 

/ 0 


P 




/ 1 


q. 




/ 2 


r 




73 


s 




74 


t 




m ~r ft 

75 


u 




76 


V 




77 


UJ 




78 


X 




79 


y 




7A 


2 




7B 


• 




7C 


i 
i 




7D 


< c 1 e a t > 


7E 


< b a 


c k > 



7F C t a b > 



•C c 1 Bar '> : : = s < or < 

•Cretur n> : : = <return> or s<return> or <return> 
•C esc > : = C esc y or s C esc > o r C esc > 
•Cspace> :: = Cspace> or sCspace> or Cspace> 

Where: s as a prefix indicates SHIFT. 

as a prefix indicates CTRL. 
/l\ as a prefix indicates ATARI key invert active. 
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Appendix 6 — Printer codes (ATASCII) 



Character set for "normal" mode printing: 



20 


<spac 


e> 40 


e 


60 




21 


1 

• 


41 


A 


61 


a 


22 


If 


42 


B 


62 


b 


23 


# 


43 


c 


63 


c 


24 


* 


44 


D 


64 


d 


25 


7. 


45 


E 


65 


e 


26 


fy. 


46 


F 


66 


f 


27 




47 


G 


67 


g 


28 


( 


48 


H 


68 


h 


29 


) 


49 


I 


69 


• 

i 


2A 


• 


4A 


J 


6A 


j 


2B 


+ 


4B 


K 


6B 


k 


2C 


f 


4C 


L 


6C 


1 


2D 




4D 


M 


6D 


m 


2E 




4E 


N 


6E 


n 


2F 


/ 


4F 


0 


6F 


o 


30 


0 


50 


P 


70 


p 


31 


1 


51 


Q 


71 


q 


32 


2 


52 


R 


72 


r 


33 


3 


53 


S 


73 


s 


34 


4 


54 


T 


74 


t 


35 


5 


55 


U 


75 


u 


36 


6 


56 


V 


76 


V 


37 


7 


57 


w 


77 


Ui 


38 


8 


58 


X 


78 


X 


39 


9 


59 


Y 


79 


y 


3A 


• 


5A 


Z 


7A 


z 


3B 


i 


5B 


C 


7B 


•C 


3C 


< 


5C 


\ 


7C 


i 
i 


3D 




5D 


3 


7D 


> 


3E 


> 


5E 




7E 




3F 


• 


5F 




7F 


<space > 



Note: the following codes print differently than defined 
the ATASCII definition. 



00 through IF print blank. 

60 prints x instead of "diamond". 

7B prints < instead of "spade". 

7D prints > instead of "clear". 

7E prints * instead of "backspace". 

7F prints blank instead of "tab". 



Character set for "sideways" mode printing: 

40 @ 60 @ 

41 A 61 A 

42 B 62 B 
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43 


C 




63 


C 






44 


D 




64 


D 






45 


E 




65 


E 






46 


F 




Ob 


F 






47 


G 




67 


G 






48 


H 




68 


H 






49 


I 




69 


I 






4A 


J 




6 A 


J 






4B 


K 




6B 


K 






4C 


L. 




oC 








4D 


M 




6D 


M 






4E 


N 




6E 


N 






4F 


a 




6F 


0 


30 


0 


5u 


p 




70 


f— » 
r 


31 


1 


51 


Q 




71 


G 


32 


2 


52 


R 




-? n 

/ c 


R 


33 


3 


53 


S 




73 


S 


34 


4 


54 


T 




74 


T 


35 


5 


55 


U 




75 


U 


36 


6 


56 


V 




76 


V 


37 


7 


^7 
t 


W 




77 




38 


8 


58 


x 






X 


39 


9 


59 


Y 




79 


Y 


3A 


• 


5A 


z 




7A 


z 




i 


: _> D 


1" 

L 




/ i_f 


i 

L 


3C 




5C 


\ 




—v — . 


•. 

\ 


3D 




5D 


J 




7D 


3 






5E 


< u p : 




7E 




3F 


• 


5F 


< left I- : 


7F 


< 1 e f t > 


Not 




the foil owing 


codes 


print 


the 


ATASCII definition 






00 


through 


2F 


print blank 




5E 


prints 


"up 


arrow" 


mstea 




5F 


prints 


"left 


arrow 


" mst 




60 


through 


7F 


repeats 


40 th 



o t 



instead of proper set 
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Appendix H — Screen mode characteristics 



Mode Horiz. Vert. Vert 
# posit, w/osp wsp 



0 



40 



Colors 



Data 
va 1 ue 



Col or 
reg. 



backqd. BAK 
OO-FF PF 2 

PF i* 



Memory 
r e qd . 

993 



1 



20 



24 



!0 



bac kqd 

00-3F 

40-7F 

80-EF 

CO-FF 



BAK 
PF 0 
PF 1 
PF 2 
PF 3 



513 



0 



10 



bac k g d 
00-3F 
40— 7F 
80-BF 
CO-FF 



BAK 
PF 0 
PF 1 
PF 2 
PF 3 



61 



40 



!0 



0 

1 

2 

3 



BAK 
PF 0 
PF 1 
PF 2 



73 



80 



48 



40 



0 
1 



BAK 
PF 0 



537 



80 



48 



40 



0 

1 

2 

3 



BAK 
PF 0 
PF 1 
PF 2 



1017 



160 



96 



80 



0 
1 



BAK 
PF 0 



2025 



160 



96 



80 



0 



2 
3 



BAK 
PF 0 
PF 1 
PF 2 



3945 



8 



320 



19; 



160 



0 
1 



PF 2 
PF 1* 



7900 



9 80 

10 80 



192 
192 



1 

9 



Note 2 

0 
1 
2 
3 
4 
5 



PM 
PM 
PM 
PM 
PF 
PF 



0 
1 

3 
O 
1 



7900 
7900 
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6 


PF 2 


7 


PF 3 


8 


B AK 


9 


BAK 


A 


BAK 


B 


BAK 


C 


PF 0 


D 


PF 1 


E 


PF 2 


F 


PF 3 



11 80 192 — 16 Note 3 7900 



Notes 



n 



Uses color 
Uses color 
Uses color 



of PF 2, lum of PF 1. 

of BAK, lum of data value (*0-F) 

of data value (*G~F>, lum of BAK 



PF x 
PM x 
BAK 



Playfield color register x. 
' Player/Missile color register x. 
Background color register (also known 



as PF 4) 



The default values for the color registers are shown below 



BAK 
PFO 
PFi 
PF2 
PF3 



*00 
$28 
*CA 
*94 
$46 



The form of a color register byte is shown below 

7 6 5 4 3 2 1 0 
+-+-+-+-+-+-+-+-+ 

! color ! lum 10! 

«j 1 1 1 i 1 1 j H 



Where: color (hex values) 



lum 



0 = 

1 = 

2 — 

3 = 

4 = 

5 = 

6 = 

7 = 

8 = 

9 - 
A = 
B = 
C = 



gray 

light orange 
or ang e 
red orange 



purp le 

pur p 1 e~b 1 ue 

blue 

blue 

light blue 
t ur quo i se 
green-b 1 ue 
green 



0 
1 
2 
3 
4 
5 
6 
7 



= minimum luminance 



(increasing 
1 urn inane e ) 



= maximum luminance 
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D = yellow-green 
E = orange-green 
F =-' light orange 
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Appendix I — Serial Bus I.D. and command summary 



Serial bus device I. D. s 



Floppy disks D1-D4 $31-34 

Printer PI $40 

RS-232-C P2 $4F 

R 1 ~R4 $50-53 



Serial bus control codes 

ACK - $41 C ' A ' > 

NAK - $4E ( ' N ' ) 

COMPLETE - $43 ( 'C ' ) 

ERR - $45 ( 'E ' ) 



Serial bus command codes 

READ ~ $52 ( 'R ' ) Disk 

WRITE - $57 ( ' W ' ) Printer/Disk 

STATUS - $53 CSM Printer/Disk 

PUT (no check) - $50 ( 'P / ) Disk 

FORMAT - $21 ( ' ! ' ) Disk 

DOWNLOAD - $20 < ' ' ) 

READADDR - $54 ( ' ) 

READ SPIN - $51 ( ■' ') Disk 

MOTOR ON - $55 ( V ) Di s k 

VERIFY SECTOR - $56 ( V ) Disk 

Appendix J — ROM vectors 



The fixed address OS RUM JMP vectors are s ho urn below- at each address 



s a JMF 


instruction 


to the 


indicated routine 


Name 


Addr 


Referenc 


e Fun c 1 1 on 


DISKIV 


E4S0 


* 




Disk h a n d 3 e r initialisation 


DSKINV 


E453 


r, 
\j . 


4. et 


Disk handler e n i r y . 


CIQV 


E456 


5. 


2 


CIO utility entry 


SIQV 


E459 


9. 


3 


S I G utility entry 


SETVBV 


E45C 


O. 


7. 2 


Set system 1 1 m e r s routine 


SYSVBV 


E45F 


o. 


3 


Stage 1 V BLANK entry. 


XITVBV 


E462 


6. 


3 


Exit VBLANK entry. 


SIOINV 


E465 






SIO utility initializatio n . 


SENDEV 


E46S 






Send enable routine. 


INTINV 


E46B 






I n t ev r u p t handler initialization 


CIQINV 


E46E 


•* 




CIO utility initidliza t ion. 


BLKBDV 


E471 


wr • 


1. 1 


Blackboard mode entry 


WAR MS V 


E474 


7. 




Warms' t ar t ( L S / RESET 3 ) ent r y 


COLDSV 


E477 


7. 




Coldstart (power up) entry. 
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RBLOKV 
C SOP IV 



E47A 
E47D 



•» 



Cassette read block entry 
Cassette OPEN input entry 



* These vectors are for OS internal use only. 



The fixed address Floating Point Package ROM routine entry point 
addresses are shown below, complete descriptions of the corresponding 
routines are provided in section 8. 



AFP 

FASC 

IFP 

FPI 

FADD 

FSUB 

FMUL 

FDIV 

LOG 

LOGIC 

EXP 

EXP 10 

PLYEVL 

ZFRO 

ZF1 

FLDOR 

FLDOP 

FLD1R 

FLD1P 

FSTOR 

FSTOP 

FMOVE 



DSOO 
DSE6 
D9AA 
D9D2 
DA66 

UHClO 

DADB 
DS28 
DECD 

n r~ <r-> «• 

uED i 
DDCO 
DDCC 
DD40 
DA44 
DA46 
DD8? 
DD8D 
DD98 
DD9C 
DDA7 
DDAB 
DDB6 



ASCII to FP convert. 
FP to ASCII convert. 
Integer to FP convert. 
FP to integer convert. 
FP add. 
FP subtract. 
FP multiply 
FP divide. 

FP base e logarithm. 

FP base 10 logarithm. 

FP base e exponentiation. 

FP base 10 exponentiation 

FP polynomial evaluation. 

Clear FRO. 

Clear FP number. 

Load FP number. 

Load FP number. 

Load FP number. 

Load FP number. 

Store FP number. 

Store FP number. 

Move FP number. 



The base addresses of the handler vectors for the resident handlers 
are shown belou;: 



Screen Editor (E) E400 

Display handler (S) E410 

Keyboard handier (K) E420 

Printer handler CP) E430 

Cassette handier <C> E440 



See section 5 for the format of the entry for each handler. 
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The 6502 Computer interrupt vector values are shown below: 

Function Address Value 

NMI FFFA E7E4 

RESET FFAC E477 

IRQ FFFE E6FE 



APPENDIX K — OS DATABASE VARIABLE FUNCTIONAL DESCRIPTIONS 

This spction contains descriptions of many of the data base variables; 
descriptions are included for all of the user accessible variables and 
for some of the "internal" variables as well. Those variables which 
are not considered to be normally of interest to any user are flagged 
with an asterisk ('*') after their names; the other variables may be 
of interest to one or more of the following classes of users: 

o End user. 

o Game developer. 

o Application programmer. 

o System utility writer. 

o Language processor developer. 

o Device handler writer. 

Each variable is specified by its system equate file name followed by 
its address (in hex) and the number of bytes reserved in the data base 
(in decimal), in the following form: 

<name> [<ad dress>, <size>] 
For e xamp 1 e : 

MEMLO C02E7, 2 3 

Note that most word (2 byte) variables are ordered with the least 
significant byte at the lower address. 

A. MEMORY CONFIGURATION 

See section 4 for a general discussion of memory dynamics and section 
7 for details of system initialization. 

Al MEMLO C02E7,23 — User free memory low address 

MEMLO contains the address of the first location in the free memory ^ 
region. The value is established by the OS during power up and L RESET J 
initialization and is never altered by the OS thereafter. 

A2 MEMTOP C02E5, 23 — User free memory high address 
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MEMTOP contains the address of the first non-useable memory location 
above the free memory region. The value is established by the OS 
during power up and CRESET3 initialization; and then is re-established 
whenever the display is OPENed. 

A3 APPMHI COOOEi 23 — User free memory screen lower limit 

APPMHI is a user controlled variable which contains the address within 
the free memory region below which the Display handler may not go in 
setting up a display screen. This variable is initialized to zero by 
the OS at power up. 

A4 RAMTOP* C006A, 1 3 — Display handler top of RAM address (msb) 

RAMTOP permanently retains the RAM top address that was contained in 
TRAMSZ (as described in Nl ) for the Display handler's use. The value 
is setup as part of handler initialization; it is not clear why this 
variable is required, since the same value is in RAMSIZ. 

A5 RAMSIZ [02E4, 13 — Top of RAM address (msb only) 

RAMSIZ permanently retains the RAM top address that was contained in 
TRAMSZ (as described in Nl). 



B. TEXT/GRAPHICS SCREEN 

See section 5 for a discussion of the text and graphics screens and 
their handlers. 

Cursor control 

For the text screen and split screen text window there is a visible 
cursor on the screen which shows the position of the next input or 
output operation. The cursor is represented by inverting the video of 
the character upon which it resides; but the cursor may be made 
invisible/ at the user's option. The graphics screen always has an 
invisible cursor. 

The cursor position is sensed by examining data base variables and may 
be moved by altering those same variables; in addition, when using the 
Screen Editor, there are cursor movement control codes which may be 
sent as data (as explained in section 5). 

Bl CRSINH C02F0, 13 — Cursor display inhibit flag 

When CRSINH is zero, all outputs to the text screen will be followed 
by a visible cursor (inverted character); and when CRSINH is non-zero., 
no visible cursor will be generated. 

CRSINH is set to zero by power up, CRESET3, CBREAK3 or an OPEN command 
to the Display handler or Screen Editor. 
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Note that altering CRSINH does not cause the visible cursor to change 
states until the next output to the screen; if an immediate change to 
the cursor state is desired; without altering the screen data* follow 
the CRSINH change with the output of CURSOR UP; CURSOR DOWN or some 
other innocuous sequence. 

B2 ROWCRS C0054, 13 & COLCRS C0055; 23 — Current cursor position 

ROWCRS and COLCRS define the cursor location (row and column; 
respectively) for the next data element to be read from or written to 
the main screen segment. When in split screen mode; the variables 
TXTROW and TXTCOL define the cursor for the text window at the bottom 
of the screen as explained in B4 below. 

The row and column numbering start with the value zero* and increase 
mono ton i ca 1 1 y to the number of rows or columns minus one; with the 
upper left corner of the screen being the origin <0;0). 

ROWCRS is a single byte variable with a maximum allowable value of 191 
(screen modes 8— 11); COLCRS is a two byte variable with a maximum 
allowable value of 319 (screen mode 8). 

B3 OLDROW C005A;13 & OLDCOL C005B; 23 — Prior cursor position 

OLDROW and OLDCOL are updated from ROWCRS and COLCRS before every 
operation. The variables are used only for the DRAW and FILL 
operations. 



B4 TXTROW C 0290* 13 & TXTCOL [0291,23 - 
p os i t i on 



- Split screen text cursor 



TXTROW and TXTCOL define the cursor location (row and column; 
respectively) for the next data element to be read from or written 
the split screen text window. 



to 



The row and column numbering start with the value zero; and increase 
mono ton i ca 1 1 y to 3 and 39, respectively; with the upper left corner of 
the split screen text window being the origin (0;0). 



Sc reen mar g ins 

The text screen and split screen text window have user alterable left 
and right margins which define the normal domain of the text cursor. 

B5 LKARGN C0052;13 — Text column left margin 

LMARGN contains the column number (0-39) of the text screen left 

margin; the text cursor will remain on or to the right of the left 

margin as a result of all operations; unless the cursor column 

variable is directly updated by the user (see B2 and B4 above). The 

default value for LMARGN is 2 and is established upon power up or 
CRESET3. 
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B6 RMARGN C0053j 1 3 — Text column right margin 

R MAR ON contains the column number (0-39) of the text screen right 
margin; the text cursor will remain on or to the left of the right 
margin as a result of all operations; unless the cursor column 
variable is directly updated by the user (see B2 and B4 above). The 
default value for RMARGN is 39 and is established upon power up or 
CRESET3. 



Color control 

As part of the stage 2 VBLANK process (see section 6), the values of 
nine data base variables are stored in corresponding hardware color 
control registers. The color registers are divided into two groups: 
the player/missile colors and the playfield colors. The playfield 
color registers are utilized by the different screen modes as shown in 
Appendix Hi the p lay er /mi ss i 1 e color registers have no use within the 
standard OS. 

B7 PCOLRO - PC0LR3 CC2C0, 43 — P 1 ay er /mi ss i 1 e colors 

Each color variable is stored in the corresponding hardware register 
as shown below: 



PCOLRO 
PC0LR1 
PC0LR2 
PCOLRO 



C02C03 
C02C1 3 
C02C23 
C02C33 



COLPNO 
C0LPM1 
C0LPM2 
C0LPM3 



CD0123 
CD0133 
CD0143 
CD0153 



Each color variable has the format shown below 



7 6 5 4 3 2 1 0 
+-+- +-+-+-+-+-+-+ 

j color i 1 urn ! x ! 



See Appendix H for information regarding the color and luminance 
field values. 

ES COLORO - C0L0R4 C02C5* 53 — Playfield colors 

Each color variable is stored in the corresponding hardware register 
as shown below: 



COLORO C02C43 

COLOR 1 C02C5 3 

C0L0R2 C02C63 

C0L0R3 L02C73 

C0L0R4 C02C83 

Each color variable 



COLPFO CD0163 
C0LPF1 CD0173 
C0LPF2 CD0183 
C0LPF3 CD0193 
COLBK CD01A3 

has the format shown below: 
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7 6 5 4 3 2 1 0 
+ — h-+— +—+-+— + — h- + 

i color ! lum J x J 
-h — i — + — h— + 

See Appendix H for information regarding the color and luminance field 
va lues. 



Text scrol 1 ing 

The text screen or split screen text window "scrolls" upward whenever 
one of the two conditions shown below occurs: 

A text line at the bottom row of the screen extends past the right 
margin. 

A text line at the bottom row of the screen is terminated by an 
EOL. 

Scrolling has the effect of removing the entire logical line that 
starts at the top of the screen and then moving all subsequent lines 
upward to fill in the void. The cursor will also move upward if the 
logical line deleted exceeds one physical line. 



B9 SCRFLG* C02BB/1D — Scroll flag 



SCRFLG is a working 
minus one that were 
logical line ranges 



variable that counts 
deleted from the top 
in size from 1 to 3; 



the number of physical lines 
of the screen; since a 
SCRFLG ranges from 0 to 2. 



Attract mode 

Attract mode is a mechanism which protects the TV screen from hav- 
ing patterns "burned into" the phosphors due to a fixed display 
being left on the screen for extended periods of time, when the 
computer is left unattended for more than 9 minutes, the color 
intensities are limited to 507. of maximum and the hues are contin- 
ually varied every 83 seconds. Pressing any keyboard data key 
will be sufficient to remove the attract mode for 9 more minutes. 

As part of the stage 2 VBLANK process, the color registers from the 
data base are sent to the corresponding hardware color registers; 
before they are sent/ they undergo the following transformation. 

hardware register = database variable XOR COLRSH AND DRKMSK 

Normally COLRSH ■ *00 and DRKMSK = $FE, thus making the above 
calculation a null operation; however/ once attract mode becomes 
active/ COLRSH = the content of RTCLOK+1 and DRKMSK = *F6.. which has 
the effect of modifying all of the colors and keeping their luminance 
always below the 50 percent level. 
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Since RTCLOK+1 is incremented every 256/60ths of a second and since 
the least significant bit of COLRSH is of no consequence; a color/Ium 
change will be effected every 83 seconds (512/60). 

BIO ATRACT C004D, ID — Attract mode timer and flag 

ATRACT is the timer (and flag) which controls the initiation and 
termination of attract mode. Whenever a keyboard key is pressed, the 
keyboard IRQ service routine sets ATRACT to zero, thus terminating 
attract mode; the CBREAK3 key logic behaves accordingly. As part of 
the stage 1 VBLANK process. ATRACT is incremented every 4 seconds, if 
the value exceeds 127 (after 9 minutes without keyboard activity), the 
value of ATRACT will then be set to $FE and will retain that value 
until attract mode is terminated. 

Since the attract mode is prevented and terminated by the OS based 
only upon keyboard activity* some users may want to reset ATRACT based 
upon ATARI controller event detection, user controlled Serial I/O bus 
ivity or any other signs of life. 



Bll COLRSH* C004F, ID — Color shift mask 

COLRSH has the value £00 when attract mode is inactive, thus effecting 
no change to the screen colors; when attract mode is active, COLRSH 
contains the current value of the timer variable middle digit 
(RTCLOK+1 ). 

B12 DRKMSK* C004E, ill — Dark (luminance) mask 

DRKMSK has the value $FE when attract mode is inactive which does not 
alter the luminance; and has the value $F6 when attract mode is active 
which forces the most significant bit of the luminance field to zero, 
thus guaranteeing that the luminance will never exceed 50 percent. 



Tab b ing 

See section 5 for a discussion of the use of tabs in conjunction with 
the Screen Editor. 

B13 TABMAP C02A3, 153 — Tab stop setting map 

The tab settings are retained in a fifteen byte (120 bit) map, where a 
bit value of one indicates a tab setting; the diagram below shows the 
mapping of the individual bits to tab positions 
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Whenevpr the Display handler or Screen Editor is opened, this map is 
initialed to contain the value of $01 in every byte., thus providing 
the default tab stops at 7. 15, 23,- etc. 



size 



Logical text lines 

Thp text screen is invisibly divided into logical lines of text, 
each comprising from one to three physical lines of text. The 
srroen is initialized to 24 logical lines of one physical line 
each; but data entry and/or data insertion may increase the si 
of a logical line to two or three physical lines. 

B14 LOGMAP* C02B2,41 — Logical i ir.e starting row map 

Thp beginning physical line number for each logical line on the 
screen is retained in a four byte (32 bit) map, where a bit 
value of one indicates the start of a logical line, the diagram 
below shows the mapping of the individual bits to physical line 
(row) numbers. 

7 6 5 4 3 2 1 0 

+ + 1- + 4 + _-+— + 

! 0! I! 2! 3! 4! 5! 6! 7! LOG MAP +0 

4- — + -+ H + + + r 

! 8 5 95lO!li:i2!l35l4:i5! + I 

+ 4 4 4 4 4 4 -1- 4 

! 16! 171 13! 19! 20! 21 ! 22 ! 23 ! +2 

+ 4 4 4 4 4 4 4 4 

!!!!!!!!! *3 

+ + + -.-+ 4 4 4 4 4 

The map bits are all set to one whenever the text screen is 
OPENed or cleared. From that point, the mar is updated as 
logical lines are entered, edited and deleted from the screen 

B15 L0GC0L» C0063, 13 — Cursor / log l ca 1 line column number 

LOGCOL contains the logical line column number for the current 
cursor position; note that a logical line may comprise up to 
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three physical lines. This variable is for the internal use of 
the Display handler. 

Split screen 

The Display handler and Screen Editor together support the 
operation of a split screen mode (see section 5) in which the main 
portion of the screen is in one of the graphics modes and is 
controlled by the Display handler, and there is a four physical line 
text window at the bottom of the screen which is controlled by the 
Screen Editor. 

E16 BOTSCR* C02BF, i 3 — Text screen lines count 

BOTSCR contains the number of lines of text for the current screen: ^4 
for mode 0 or 4 for a split screen mode. The handler also uses this 
variable as an indication of the split screen status; tests are made 
for the specific values 4 and 24. 



DRAW/FILL function 

The E>RAW function line drawing algorithm is shown below translated to 
the Pascal language from assembly language. 

NEWROW : * ROWCRS; NEWCOL : ■ COLCRS; * 

DELTAR := AES < NEWROW-OLDROW ) ; 

ROWINC := SIGN ( NEWROW-OLDROW ) \ < +1 or -1 > 
DELTAC : = AES ( NEWCOL-OLDCOL ) s 

COLINC := SIGN (NEWCOL-OLDCOL); < +1 or -1 > 

ROWAC : * C; COLAC « 0; 

ROWCRS : = OLDROWi COLCRS : = OLDCOL; 

COUNTR : = MAX ( DELTAC , DELTAR ) ; 
ENDPT : = COUNTR; 
IF COUNTR - DELTAC 

THEN ROWAC := ENDPT DIV 2 

ELSE COLAC := ENDPT DIV 2; 

WHILE COUNTR > 0 DO 
BEGIN 

ROWAC := ROWAC + DELTAR; 
IF ROWAC >= ENDPT 
THEN 

BEGIN 

ROWAC : = ROWAC - ENDPT; 
ROWCRS : = ROWCRS + ROWINC 

END; 
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COLAC := COLAC + DELTAC; 
IF COLAC >= ENDPT 
THEN 

BEGIN 

COLAC := COLAC - ENDPT; 
COLCRS := COLCRS + COLINC 
END; , 

PLOT..POINT; < point defined by ROWCRS & COLCRS > 
IF FILFLG O 0 THEN F I LL_L I NE; 
COUNTR : = COUNTR - 1 
END; 

The FILL function algorithm (FILLJ-INE above) is described briefly in 
section 5. 

B17 FILDAT C02FD, 13 — Fill data 

FILL contains the fill region data value as part of the calling 
sequence for a FILL command as described in section 5. 

B18 FILFLG* C 02B7# 1 3 — Fill flag 

FILFLG indicates to shared code within the Display handler whether the 
current operation is FILL (FILFLG O 0) or DRAW (FILFLG = 0). 

B19 NEWROW* C0060.1D & NEWCOL* [0061,23 — Destination point 

NEWROW and NEWCOL are initialized to the values in ROWCRS and COLCRS- 
which represent the destination endpoint of the DRAW/FILL command. 
This is done so that ROWCRS and COLCRS may be altered during the 
performance of the command. 

B20 H0LD4* [02BC13 — Temporary storage 

H0LD4 is used to save and restore the value in ATACHR during the 
FILL process; ATACHR is temporarily set to the value in FILDAT 
to accomplish the filling portion of the command. 

B21 ROWINC* C0079, 13 ?< COLINC* C007A, 13 — Row/column 
increment/decrement 

ROWINC and COLINC are the row and column increment values; they are 
each set to +1 or -1 to control the basic direction of line drawing. 
ROWINC and COLINC represent the signs of NEWROW - ROWCRS and NEWCOL - 
COLCRS/ respectively. 

B22 DELTAR* £0076,13 & DELTAC* [0077,23 — Delta row and delta 
col umn 
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• 

DELTAR and DELTAC contain the absolute values of NEWROW - ROWCRS and 
NEWCOL - COLCRS, respectively; together with ROWING and COLINC, they 
define the slope of the line to be drawn. 

B23 COUNTR* C007E, 23 — Draw iteration count 

COUNTR initially contains the larger of DELTAR and DELTAC, which is 
the number of iterations required to generate the desired line. COUNTR 
is then decremented after every point on the line is plotted, until it 
reaches a value of zero. 

B24 ROWAC* C0070, 23 & COLAC* [0072, 23 — Accumulators 

ROWAC and COLAC are working accumulators which control the row and 
column point plotting and increment (or decrement) function. 

E25 ENDPT* C0074, 23 — Line length 

ENDPT contains the larger of DELTAR and DELTAC, and is used in 

conjunction with ROWAC /COLAC and DELTAR /DELTAC to control the plotting 
of 1 ine points. 



Displaying control characters 

Often it is useful to have ATASCII control codes (such as CLEAR, 
CURSOR UP, etc. ) displayed in their graphic forms instead of having 
them perform their control function. This display capability is 
provided in two forms when outputting to the Screen Editor: 1) a data 
content form in which a special character (ESC) preceeds each control 
character to be displayed and 2) a mode control form. 



Escape (display following control character) 

Whenever an ESC character is detected by the Screen Editor, the 
next character following this code is displayed as data, 
even if it would normally be treated as a control code; the EOL 
code is the sole exception, it is always treated as a control 
code. The sequence ESC ESC will cause the second ESC character 
to be displayed. 

B26 ESCFLG* C02A2, 13 — Escape flag 

ESCFLG is used by the Screen Editor to control the escape 
sequence function; the flag is set (to $80) by the detection of 
an ESC character ($1B> in the data stream and is reset (to O) 
following the output of the next character. 

Display control characters mode 

When it is desired to display ATASCII control codes other than EOL in 
their graphics form, but not have an ESC character associated with 
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each control code/ a display mode may be established by setting a flag 
in the data base. This capability is used by language processors when 
displaying high level language statements/ which may contain control 
codes as data elements. 

B27 DSPFLG C02FE/13 — Display control characters flag 

When DSPFLG is non-zero, ATASCII control codes other than EOL are 
treated as data and displayed on the screen when output to the Screen 
Editor. When DSPFLG is zero, ATASCII control codes are processed 
norma 1 1 y . 

DSPFLG is set to zero by power up and CRESET3. 



Bit mapped graphics 

A number of temporary variables are used by the Display handler when 
handling data elements (pixels) going to or from the screen; of 
interest here are those variables which are used to control the 
packing and unpacking of graphics data/ where a memory byte typically 
contains more than one data element (for example/ screen mode 8 
contains 8 pixels per memory byte). 

B28 DMASK* C02A0/13 — Pixel location mask 

DMASK is a mask which contains zeroes for all bits which do not 
correspond to the specific pixel to be operated upon, and which 
contains ones for all bits which do correspond. DMASK may contain the 
values shown below in binary notation: 

11111111 — screen modes 1 ?y 2; one pixel per byte. 

llllOOOO — screen modes 9-11; two pixels per byte. 
00001111 

11000000 — screen modes 3/ 5 & 7; four pixels per byte. 

00110000 

00001100 

00000011 



10000000 — screen modes 4* 6 & 8; eight pixels per byte. 
01000000 

00000010 
00000001 

B29 SHFAMT* C006F, 13 — Pixel justification 

SHFAMT indicates the amount to shift the right justified pixel data on 
output/ or the amount to shift the input data to right justify it on 
input. The value is always the same as for DMASK prior to the 
justification process. 
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Internal working variables 

E30 HOLD1* [0051*13 — Temporary storage 
B31 H0LD2* C029F, 13 — Temporary storage 
B32 HOLDS* C029D, 13 — Temporary storage 
E33 TMPCHR* [0050*13 — Temporary storage 
B34 DSTAT* CGG4C13 — Display status 
E35 DINDEX* C0057, 13 — Display mode 

DINDEX contains the current screen mode obtained from the low order 
four bits of the most recent OPEN AUX1 byte. 

B36 SAVMSC C 0058* 23 — Screen Memory Address 

SAVMSC contains the lowest address of the screen data region; the 
data atthat address is displayed at the upper left corner of the 
screen. 

E37 OLDCHR* C005D* 13 — Cursor character save/restore 

OLDCHR retains the value of the character under the visible text 
cursor; this variable is used to restore the original character value 
when the cursor is moved. 

B38 QLDADR* C005E, 23 — Cursor memory address 

OLDADR retains the memory address of the current visible text cursor 
location; this variable is used in conjunction with OLDCHR (B37) to 
restore the original character value when the cursor is moved. 

B39 ADRESS* [0064/ 23 — Temporary storage 

B40 ML T TUP /OPNTMP / TO ADR* C0066# 23 — Temporary storage 

B41 SAVADR/FRMADR* 1 0068/ 23 — Temporary storage 

B42 BUFCNT* C006B# 13 — Screen Editor current logical line size 

B43 BUFSTR* C006C23 — Temporary storage 

B44 SUiPFLG* C007B* 1 3 — Split screen cursor control 

In split screen mode the graphics cursor data and the text window 
cursor data are frequently swapped as shown below in order to get the 
variables associated with the region being accessed into the 
ROWCRS-OLDADR variables. 

ROWCRS B2 TXTROW B4 

COLCRS B2 TXTCOL B4 
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D INDEX B35 T INDEX B49 

- TXTMSC B52 



SAVMSC B36 

OLDROW B3 TXTOLD B53 

OLDCOL B3 

OLDCHR B37 

OLDADR B38 

SWPFLG is used to keep track of which data set is currently in the 
ROWCRS-OLDADR region; SWPFLG is equal to *FF when split screen text 
window cursor data is in the main region/ otherwise SWPFLG is equal to 



0. 








B45 


INSDAT* 


[007D, 1 3 


— Temporary storage 


B46 


TMPROW* 


C02B8, 13 


?s. TNPCOL* C02B9, 23 — Temporary storage 


B47 


TMPLET* 


C02A1, 1 3 


• 

— Temporary storage 


348 


SUBTMP* 


C029E, 13 


— Temporary storage 


B49 


TINDEX* 


[0293, 13 


— Split screen text window screen mode 



TINDEX is the split screen text window equivalent of DINDEX and is 
always equal to zero when SWPFLG is equal to zero (see B44) 

B50 BITMSK* C006E,,13 — Temporary storage 

B51 LINBUF* C0247, 403 — Physical line buffer 

LINBUF is used to temporarily buffer one physical line of text when 
the Screen Editor is moving screen data. 

B52 TXTMSC [0294,23 — Splitscreen memory address 

TXTMSC is the split screen text window version of SAVMSC (36). 

See B44 for more information. 

B53 TXTOLD* £0296, 63 — Split screen cursor data 
See B44 for more information. 

Internal character code conversion 

Two variables are used to retain the current character being processed 
(for both reading and writing); ATACHR contains the value passed to or 
from CIO/ and CHAR contains the internal code corresponding to the 
value in ATACHR. Because the hardware does not interpret ATASC I I 



characters directly 



i the transformations shown below are applied to 



all text data read and written: 

ATASC 1 1 INTERNAL 
CODE CODE 
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00- IF 
20-3F 
40-5F 
60-7F 
80-9F 
AO-BF 
CO-DF 
EO-FF 



40-5F 
00-1F 
20-3F 
60-7F 
CO-DF 
80-9F 
AO-BF 
EO-FF 



See P26 for more information. 

B54 ATACHR C02FB/1D — Last ATASCII character or plot point 

ATACHR contains the ATASCII value for the most recent character read 
or written/ or the value of the graphics point. This variable may also 
be considered to be a parameter of the FILL/DRAW commands/ as the 
value in ATACHR will determine the line color when a DRAW or FILL is 
performed. 

B55 CHAR* C02FA/1D — Internal character code 

CHAR contains the internal code value for the most recent charcter 
read or written. 



C. DISK HANDLER 

See section 5 for a discussion of the resident Disk handler. 
CI BUFADR* [0015,23 — Data buffer pointer 

BUFADR acts as temporary page zero pointer to the current disk 

b uf f er . 

C2 DSKTIM* C0246/13 — Disk format operation timeout time 

DSKTIM contains the timeout value for SIO calling sequence variable 
DTIMLO (see section 9); DSKTIM is set to 160 (which represents 3 171 
second timeout) at initialization time/ and is updated after each disk 
status request operation contain the value returned in the 3rd byte of 
the status frame (see section 5). Note that all disk operations other 
than format have a fixed (7) second timeout/ established by the Disk 
handler. 



D. CASSETTE 

See section 5 for a general description of the Cassette handler. The 
cassette uses the Serial I/O bus hardware/ but does not conform with 
the Serial I/O bus protocol as defined in section 9. Hence/ the Serial 
I/O utility (SIO) has cassette specific code within it. Some variables 
in this sub-section are utilized by SIO and some by the Cassette 
hand ler . 
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Cassette mode 

D8 CASFLG* C030F, 13 — Cassette I/O flag 

CASFLG is used internally by SIO to control the program flow through 
shared code. A value of zero indicates that the current operation is a 
standard Serial I/O bus operation^ and a non-zero value indicates a 
cassette operation. 

Cassette buffer 

D9 CASBUF* C03FD/ 1313 — Cassette record buffer 

CASBUF is the buffer used by the Cassette handier for the packing and 
unpacking of cassette record data- and by the initialization cassette- 
boot logic. The format for the standard cassette record in the buffer 
is shown below: 

7 6 5 4 3 2 1 0 
+-+- 1-~ + --+-+-+-+-+ 

10 1 0 1 0 1 0 1 : CASBUF+O 

+ - + - + - + — -f — i i >- — h 

10 10 10 10 1! +1 

* — H 1 i h — H i 1 h 

! control by te ! i-2 

+ — h-H J~ — H — I i h — + 

! 128 ! +3 

= data « 

1 bytes ! +130 

+—+-+— + -+-+- 

See section 5 for an explanation of the standard cassette record 
format. 

D10 BLIM* C028A/13 — Cassette record data size 

BLIM contains the count of the number of data bytes in the current 
cassette record being read. ELIM will have a value ranging from i to 
128 i depending upon the record control byte as explained in section 5 

Dll BPTR* C003D*13 — Cassette record data index 

BPTR contains an index into the data portion of the cassette record 
being read or written. The value will range from O to the then cut- rent 
value of BLIM. When BPTR equals BLIM then the buffer (CASBUF) is full 
if writing or empty if reading. 

Internal working varibles 

T>12 FEOF* L003F, 13 — Cassette end of file flag 

FEOF is used by the cassette handler to flag the detection of an end 
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Baud rate determination 

The input baud rate is assumed to be a nominal 600 baud/ but will be 
adjusted/ if necessary/ by the SiO routine to account foT drive motor 
variations/ stretched tape/ etc. The beginning of every cassette 
record contains a pattern of alternating ones and zeroes which is used 
solely for speed correction; by measuring the time to read a fixed 
number of bits/ the true receive baud rate is determined and the 
hardware adjusted accordingly. Input baud rates ranging from 318 to 
1407 baud can theoretically be handled using this technique 

The input baud rate is adjusted by setting the POKEY counter which 
controls the bit sampling period. 

Dl CBAUDL* L02EE/13 & CBAUDH* C02EF, 13 — Cassette baud rate 

Initialized to 05CC hex, which represents a nominal 600 baud 
After baud rate calculation/ these variables will contain POKEY 
counter values for the corrected baud rate 

D2 TIMFLG* [0317/13 — Baud rate determination time out flag 

TIMFLG is used by SIO to timeout an unsuccessful baud rate 
determination. The flag is initially set to one, and if it attains a 
value of zero (after 2 seconds) before the first byte of the cassette 
record has been read, the operation will be aborted. See also H24 

D3 TIMER1* C030C23 & TIMER2* C0310/ 2D — Baud rate timers 

These timers contain reference times for the beginning and end of the 
fixed bit pattern receive period. The first byte of each timer 
contains the then current vertical line counter value read from ANTIC 
and the second byte of each timer contains the then current value 'of 
the least significant byte of the OS real time clock (RTCLOK+2). 

The difference between the timers is converted to raster pair counts 
and is then used to perform a table lookup with interpolation to 
determine the new values for CBAUDL and CBAUDH. 

D4 ADDCOR* C030E/13 — Interpolation adjustment variable 

ADDCOR is a temporary variable used for the interpolation calculation 
of the above computation. 

D5 TEMPI* C0312* 23 — Temporary storage 
D6 TEMP3* L0315/13 — Temporary storage 
D7 SAVIO* L0316/13 — Serial in data detect 

SAVIO is used to retain the state of SKSTAT CD20F3 bit-4 (serial data 
in); it is used to detect (and is updated after) every bit arrival 
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of file condition (control byte = *FE>. FEOF equal to zero indicates 
that an EOF has not yet been detected/ and a non-zero value indicates 
that an EOF has been detected. The flag is reset at every OPEN. 

D13 FTYPE* C003E, 13 — Inter-recdrd gap type 

FTYPE is a copy of ICAX22 from the OPEN command and indicates the type 
of inter-record gap selected; a positive value indicates normal record 
gaps, and a negative value indicates continuous mode gaps. 

D14 WMODE* C0289, 13 — Cassette read/write mode flag 

WMODE is used by the cassette handler to indicate whether the current 
operation is a read or write operation; a value of zero indicates 
read, and a value of $80 indicates write. 

D15 FREQ* [0040,13 — Beep count 

FREQ is used to retain and count the number of beeps requested of the 
'EEEP routine by the Cassette handler during the OPEN command 
process. 

E. KEYBOARD 

See section 5 for a general description of the Keyboard handler. 
Key reading and debouncing 

The console key code register is read in response to an IRQ interrupt 
which is generated whenever a key stroke is detected by the hardware. 
The key code is compared with the prior key code accepted (CHI); if 
the codes are not identical/ then the new code is accepted and stored 
in the key code FIFO (CH) and in the prior key code variable (CHI). If 
the codes are identical/ then the new code is accepted only if a 
suitable key debounce delay has transpired since the prior value was 
accepted. 

If the key code read and accepted is the code for CTRL-l* then the 
display start/stop flag ( SSFLAG > is complemented and the value is not 
stored in the key code FIFO (CH). 

In addition to the reading of the key data, SRTIMR is set to $30 for 
all interrupts received (see E8 ) , and ATRACT is set to 0 whenever a 
new code is accepted (see BIO). 

The Keyboard handler obtains all key data from CH; whenever a code is 
extracted from that one-byte FIFO/ the handler stores a value of *FF 
to the FIFO to indicate that the code has been read. See section 5 for 
further discussion of the Keyboard handler's processing of the key 
codes. 

El CHI* C02F2/13 — Prior keyboard character code. 
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CHI contains the key code value of the key most recently read and 
accepted. 

E2 KEYDEL* C02F1,13 — Debounce delay timer. 

KEYDEL is set to a value of 3 whenever a key code is accepted/ and is 
decremented every 60th of a second by the stage 2 VBLANK process 
(until it reaches zero). 

E3 CH C02FC13 — Keyboard character code FIFO. 

CH is a one-byte FIFO which contains either the value of the most 
recently read and accepted key code or the value *FF (which indicates 
that the FIFO is empty). The FIFO is normally read by the keyboard 
handler* but may be read by a user program. 

Key data may also be stored into CH by the auto-repeat logic as 
explained in the discussion relating to E8. 



Special functions 



Start/stop 

Display handler and Screen Editor output to the text or graphics mode 
screen may be stopped and started (without losing any of the output 
data) through the use of the CTRL-1 key combination. Each key 
depression toggles a flag which is monitored by the above mentioned 
handlers. When the flag is non-zero, the handlers wait for it to go to 
zero before continuing any output. 

E4 SSFLAG C02FF, 1 3 ~ Start/stop flag 

The flag is normally zero, indicating that screen output is not to be 

stopped. The flag is complemented by every occurrence of the CTRL-1 
key combination by the keyboard IRQ service routine. 

The flag is set to zero upon power up, CRESET3 or [BREAK] key 
processing. 

CBREAK3 key 

E5 BRKKEY £0011,13 — CBREAK3 key flag 

BRKKEY is used to indicate that the CBREAK3 key has been pressed. The 
value is normally non-zero and is set to zero whenever the CBREAK3 key 
is pressed. The code that detects and processes the CBREAK3 condition 
(flag ■ O) should set the flag non-zero again. 

BRKKEY is monitored by the following OS routines: Keyboard handler, 
Display handler, Screen Editor, Cassette handler, xx? The detection of 
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a CBREAK3 condition during an I/O operation* will cause the operation 
to be aborted and a status of $80 to be returned to the user. 

The flag is set non-zero upon power up# CRESET3 or upon aborting a 
pending I/O operation. 

SHIFT/CONTROL lock 

The keyboard control has three different modes for code generation 
which apply to the alphabetic keys 'A' through 'Z': 1) normal* 2) caps 
lock and 3) control lock. 

In normal mode/ all unmodified alphabetic character keys generate the 
lower case letter ATASCII code (*61-7A>. 

In caps lock mode* all unmodified alphabetic character keys generate 
the upper case letter ATASCII code ($41-5A>. 

In control lock mode/ all unmodified alphabetic character keys 
generate the control letter ATASCII code (*01-1A). 

In all three modes* any alphabetic character key which is modified (by 
being pressed in conjunction with the SHIFT or CONTROL key) will 
generate the desired modified code. 

E6 SHFLOK C02BE/13 — Shift/control lock control flag 

SHFLOK normally has one of three values: 

*00 = normal mode (no locks in effect). 
$40 = caps lock. 
*S0 = control lock. 

SHFLOK is set to $40 upon power up and CRESET3 and is modified 
thereafter by the OS only when the CAPS key is pressed (either by 
itself or in conjunction with the SHIFT or CTRL key). 

E7 HOLDCH* C007C/13 — Character holding variable 

HOLDCH is used to retain the current character value prior to 
the SHIFT/CONTROL logic process. 



Auto-rep eat 

The auto-repeat feature responds to the continuous depression of a 
keyboard key by replicating the key code 10 times per second/ after an 
initial 1/2 second delay. The timer variable SRTIMR is used to control 
both the initial delay and the repeat rate. 

Whenever SRTIMR is equal to zero and a key is being held down, the 
value of the key code is stored in the key code FIFO (CH). This logic 
is part of the stage 2 VBLANK process. 
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E8 SRTIMR* l022B: 1 3 — auto-repeat timer 

SRTIMR is controlled by two independent processes: 1) the 
keyboard IRQ service routine/ which establishes the initial 
delay value and 2) the stage 2 VELANK Routine which establishes 
the repeat rate/ decrements the timer and implements the auto- 
repeat log ic. 

Inverse video control 

The Keyboard handler allows the direct generation of a more than half 
of the 256 ATASCII codes; but codes *80-9A and codes $AO- FC can be 
generated only with the "inverse video mode" active. The ATARI key 
acts as an on/off toggle for this mode, and all characters (except for 
screen editing control characters) will be subject to inversion when 
the mode is active. 

E9 INVFL.G C02B6/1] — inverse video flag 

INVFLG is normally zero, indicating that normal video ATASCII 
codes (bit-7 = O) are to be generated from keystrokes; however, 
whenever INVFLG is non-zero., inverse video ATASCII codes (bit-7 
■ 1) will be generated. The special control codes are exempt 
from this bit manipulation. 

INVFLG is set to zero by power up and CRESETD. 

The Keyboard handler inverts bit-7 of INVFLG whenever the ATARI key is 
pressed; the lower order bits are not altered and are assumed to be 
zero. 

The Keyboard handler "exculsive or"s the ATASCII key data with the 
value in INVFLG at all times; the normal values of $00 and $80 thus 
lead to control of the inverse video bit (bit-7). 



Console switches (SELECT, START & OPTION) 

The console switches are sensed directly from the hardware 
register CONSOL CDOiFj; see the Colleen hardware manual for 
details. 

F. PRINTER 

See section 5 for a general description of the Printer handler. 
Printer buffer 

Fl PRNBUF* C03C0, 40j — Printer record buffer 

PRNBUF is the buffer used by the Printer handler for packing printer 
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data to be sent to the device controller. The buffer is 40 bytes long 
and contains nothing but printer data. 

F2 PBUFSZ* C001E>13 — Printer record size 

PBUFSZ contains the size of the printer record for the current mode 

selected; the modes and respective sizes (in decimal bytes) are shown 
below: 

Normal 40 

Double width 20 (not currently supported by the device) 

Sideways 29 

Status request 4 

F3 PBPNT* C001D, 11 — Printer buffer index 

PBPNT contains the current index to the printer buffer. PBPNl ranges 
in value from zero to the value of PBUFSZ. 

Internal working variables 

F4 PTEMP* C001F/13 — Printer handler temporary data save 

PTEMP is used by the Printer handler to temporarily save the value of 
a character to be output to the printer. 

F5 PTIMOT* C001C/13 — Printer timeout value 

PTIMOT contains the timeout value for SIO calling sequence variable 
DTIMLO (see section 9); PTIMOT is set to 30 (which represents a 32 
second timeout) at int ia 1 i za t i on time, and is updated after each 
printer status request operation to contain the value returned in the 
3rd byte of the status frame (see section 5). 



0. CENTRAL I/O ROUTINE (CIO) 

See section 5 for a description of the Central I/O Utility. 
User call parameters 

CIO call paramters are passed primarily through an I/O Control 
Block (IOCB); although additional device status information may 
be returned in DVSTAT, and handler information is obtained from 
the Device Table (HATABS). 
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I/O Control Block 

IOCB is the name applied collectively to the 16 bytes associated with 
each of the 8 provided control structures; see section 5. 

Gl IOCB C0340, 163 — I/O Control Block 

The label IOCB is the location of the first byte of the first IOCB in 
the data base. For VIDs G2 through 010/ the addresses given are for 
IOCB #0 only., the addresses for all of the IOCBs are shown below: 





0340-034F 


IOCB #0 




0350-035F 


IOCB #1 




O \~j £• U U Jur 


IOCB #2 




0370-037F 


IOCB #3 




0380-038F 


IOCB #4 






IOCB #5 




03A0-03AF 


IOCB #6 




03B0-03BF 


IOCB #7 


G2 


I CHID C0340, l ] — 


Hand 1 er I . D. 


See 


section 5 . Initial 


] zed to $FF at power up and [RESET 3. 


G3 


ICDNO C0341 , i 3 — 


Device number 


P. e © 


s e c t i o n 5 . 




54 


ICC Oh C0342, I 3 — 


Command byte 


See 


section 5 . 




G5 


ICSTA {10343, 1 3 — 


S t at us 


See 


section 5 . 




G6 


I C B AL i I C B AH [ 0344 , 


2 3 — B u f f er add r e s s 


See 


section 5. 




57 


I CPTLj 1CFTH f. 0346, 


2 3 — PUT BYTE vector 


See 


section 5. Initialized to point to CIO'.* " IOCB not OPEN' 5 


at 


power up and [RESET 


j . 


GB 


ICBLL* ICBLH [0343, 


2] — Buffer length / byte count 


See 


section 5. 




G9 


ICAX1, I C A X 2 L034A. 


2 3 — Auxvlliary information 


See 


section 5 




G 1 0 


ICSPR C034C. 4 j — 


■ Spare bytes for handle r u s e 
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There is no fixed assignment of these four bytes; the handler 
associated with an IOCB may or may not use these bytes. 

Device status 

Gil DVSTAT C02EA,4D — Device status 

See section 5 for a discussion of the GET STATUS command 
Device Table 

G12 HAT AES L 031 A/ 38 D — Device Table 
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